Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

156 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
// Unified submission face: BatchBuilder is the ONLY DrawCommand producer, and every
// stream (Batch quads, shape vertices, particle instances) routes through it. Drives
// pushBatchDraw / appendIndexedDraw / appendQuad against a real TransientBufferPool +
// DrawList over the MockGfxDevice and asserts the per-stream baseVertex math, the
// texture-slot rules, instanced command assembly, sort/merge behavior, clip stamping,
// and execute() dispatch — the invariants the per-plugin hand-rolled paths used to own.
#define DOCTEST_CONFIG_IMPLEMENT_WITH_MAIN
#include <cmath>
#include <doctest.h>

#include "MockGfxDevice.hpp"
#include "esengine/renderer/draw/BatchBuilder.hpp"
#include "esengine/renderer/draw/ImmediateDraw.hpp"
#include "esengine/renderer/draw/DrawList.hpp"
#include "esengine/renderer/store/MaterialStore.hpp"
#include "esengine/renderer/rhi/TransientBufferPool.hpp"
#include "esengine/renderer/frame/RenderFrame.hpp"
#include "esengine/renderer/frame/RenderContext.hpp"
#include "esengine/resource/ResourceManager.hpp"
#include "esengine/renderer/plugins/UIElementPlugin.hpp"
#include "esengine/renderer/plugins/TextPlugin.hpp"
#include "esengine/renderer/plugins/SpritePlugin.hpp"
#include "esengine/renderer/plugins/TilemapRenderPlugin.hpp"
#include "esengine/ecs/components/TilemapLayer.hpp"
#include "esengine/ecs/components/Sprite.hpp"
#include "esengine/ecs/components/BitmapText.hpp"
#include "esengine/ecs/components/UINode.hpp"
#include "esengine/ecs/components/UIVisual.hpp"
#include "esengine/ecs/components/UIMask.hpp"
#include "esengine/ecs/components/ContentRect.hpp"
#include "esengine/ecs/components/Interactable.hpp"
#include "esengine/ui/UISystem.hpp"
#include "esengine/ecs/FlatGeometry.hpp"
#include "esengine/ecs/TransformSystem.hpp"
#include "esengine/ecs/components/Hierarchy.hpp"

#include <functional>
#include <limits>
#include <utility>
#include <vector>

using namespace esengine;

TEST_CASE("presented primitives retain depth state and order until the scene pass") {
    MockGfxDevice device;
    std::vector<PipelineDesc> states;
    std::vector<u32> offsets;
    device.observeDrawElements = [&](const PipelineDesc& state, u32 offset) {
        states.push_back(state);
        offsets.push_back(offset);
    };
    RenderContext context(device);
    resource::ResourceManager resources;
    resources.init(device);
    ImmediateDraw draw(device, context, resources);
    draw.init();
    draw.begin(glm::mat4(1.0f), 800, 600);
    draw.deferBegin();
    const int uploads = device.updateBufferCalls;
    const auto line = [&] { draw.line({0, 0}, {10, 0}, {1, 0, 0, 1}, 2); };
    line();
    draw.setDepthState(false, false);
    line();
    draw.setDepthState(true, false);
    line();
    draw.setDepthState(false, true);
    CHECK(device.drawElementsCalls == 0);
    CHECK(device.updateBufferCalls == uploads);
    draw.deferEnd();
    CHECK(device.drawElementsCalls == 0);
    draw.flushDeferred();
    REQUIRE(states.size() == 3);
    CHECK_FALSE(states[0].depthTest);
    CHECK(states[0].depthWrite);
    CHECK_FALSE(states[1].depthTest);
    CHECK_FALSE(states[1].depthWrite);
    CHECK(states[2].depthTest);
    CHECK_FALSE(states[2].depthWrite);
    CHECK((offsets == std::vector<u32>{0, 6 * sizeof(u32), 12 * sizeof(u32)}));
    draw.flushDeferred();
    CHECK(device.drawElementsCalls == 3);
    draw.begin(glm::mat4(1.0f), 800, 600);
    line();
    draw.end();
    CHECK(device.drawElementsCalls == 4);
    CHECK(offsets.back() == 0);
    draw.shutdown();
    resources.shutdown();
}

namespace {

struct Harness {
    MockGfxDevice device;
    TransientBufferPool pool{device};
    DrawList list;
    ClipState clips;

    Harness() {
        pool.init(64 * 1024, 16 * 1024);
        pool.beginFrame();
    }
    ~Harness() { pool.shutdown(); }
};

struct NineSlicePlugin : UIElementPlugin {
    using BatchPlugin::emitNineSlice;
    using BatchPlugin::emitRadialFill;
};

BatchDrawKey quadKey(u32 textureId, i32 layer = 0) {
    BatchDrawKey key{};
    key.stage = RenderStage::Transparent;
    key.layer = layer;
    key.shaderId = 7;
    key.blend = BlendMode::Normal;
    key.textureId = textureId;
    key.type = RenderType::Sprite;
    return key;
}

// The 48-byte record the Shape stream is laid out for (mirrors ShapePlugin's format).
struct TestShapeVertex {
    f32 px, py, ux, uy;
    f32 cr, cg, cb, ca;
    f32 shapeType, halfW, halfH, cornerRadius;
};
static_assert(sizeof(TestShapeVertex) == 48, "shape record must match the Shape stream stride");

// The per-instance slot the ParticleInstance stream is laid out for (mirrors ParticlePlugin's).
struct TestParticleInstance {
    f32 px, py, pz;
    f32 sx, sy;
    f32 rotation;
    u32 color;
    f32 uvOffsetX, uvOffsetY;
    f32 uvScaleX, uvScaleY;
};
static_assert(sizeof(TestParticleInstance) == 44,
              "instance record must match the ParticleInstance stream stride");

}  // namespace

TEST_CASE("pool reports each stream's vertex stride (single source for baseVertex math)") {
    Harness h;
    CHECK(h.pool.vertexStride(LayoutId::Batch) == sizeof(BatchVertex));
    CHECK(h.pool.vertexStride(LayoutId::Shape) == sizeof(TestShapeVertex));
    CHECK(h.pool.vertexStride(LayoutId::ParticleInstance) == sizeof(TestParticleInstance));
}

TEST_CASE("tilemaps: rotation places cached quads and inverts distant chunk culling") {
    for (auto grid : {tilemap::GridType::Orthogonal, tilemap::GridType::Isometric,
                      tilemap::GridType::StaggeredIsometric, tilemap::GridType::Hexagonal}) {
        for (bool infinite : {false, true}) for (bool lazy : {false, true}) {
            Harness h;
            RenderContext context(h.device);
            resource::ResourceManager resources;
            resources.init(h.device);
            const u8 pixels[16 * 24 * 4] = {};
            const auto texture = resources.createTexture(resource::ResourceContent::Retained,
                16, 24, pixels, TextureFormat::RGBA8);
            ecs::Registry registry;
            const auto entity = registry.create();
            auto& transform = registry.emplace<ecs::Transform>(entity);
            auto& component = registry.emplace<ecs::TilemapLayer>(entity);
            component.tileset = texture; component.tilesetColumns = 1;
            component.cellSize = {16, 24}; component.originOffset = {3, -2};
            tilemap::TilemapSystem system;
            if (infinite) system.initInfiniteLayer(entity, 16, 24);
            else system.initLayer(entity, 96, 16, 16, 24);
            system.setGridType(entity, grid); system.setHexParams(entity, 6, true, false);
            const i32 tx = infinite ? -33 : 64, ty = 2;
            system.setTile(entity, tx, ty, 1);
            f32 lx = 0, ly = 0;
            system.tileToWorld(entity, tx, ty, 0, 0, lx, ly);
            if (grid != tilemap::GridType::Isometric) { lx += 8; ly -= 12; }
            const glm::vec3 localCenter{lx + 3, ly - 2, 0}, origin{20, 30, 0};
            Frustum frustum;
            RenderFrameContext frameContext{context, resources};
            RenderCollectContext collect{registry, frustum, h.clips, h.pool, h.list, frameContext, {}};
            const auto revision = system.getLayerData(entity)->edit_revision;
            for (f32 angle : {0.0f, .37f, glm::half_pi<f32>(), glm::pi<f32>(), -glm::half_pi<f32>()}) {
                // A plugin per angle: a layer placed anew from one collect to the next is treated as moving and built per frame, which is
                // another test's subject; here each angle is the first time the layer is seen at it.
                TilemapRenderPlugin plugin; plugin.setTilemapSystem(&system); plugin.init(frameContext);
                const auto rotation = glm::angleAxis(angle, glm::vec3{0, 0, 1});
                transform.worldPosition = origin; transform.worldRotation = rotation;
                transform.cachedMatrix_ = glm::translate(glm::mat4{1}, origin) * glm::mat4_cast(rotation);
                transform.decomposed_ = !lazy;
                const auto center = origin + rotation * localCenter;
                const auto projection = glm::ortho(center.x - 4, center.x + 4, center.y - 4, center.y + 4);
                frustum.extractFromMatrix(projection); collect.camera = computeCameraView(projection);
                h.pool.beginFrame(); h.list.clear(); h.device.createdBuffers.clear(); plugin.collect(collect);
                // The layer draws from a strip the GPU holds, so the quad is in the buffer made for it, not in the frame's pool: a draw that names
                // that buffer, for the one tile's six indices.
                REQUIRE(h.list.commandCount() == 1);
                REQUIRE(h.list.command(0).hasPersistentGeometry());
                CHECK(h.list.command(0).index_count == 6);
                REQUIRE(h.pool.vertexBytesUsed(LayoutId::Batch) == 0);
                const MockGfxDevice::CreatedBuffer* vertexBuffer = nullptr;
                for (const auto& made : h.device.createdBuffers) if (made.desc.usage == GfxBufferUsage::Vertex) vertexBuffer = &made;
                REQUIRE(vertexBuffer != nullptr);
                REQUIRE(vertexBuffer->bytes.size() == 4 * sizeof(BatchVertex));
                const auto* vertices = reinterpret_cast<const BatchVertex*>(vertexBuffer->bytes.data());
                const glm::vec3 offsets[] = {{-8, -12, 0}, {8, -12, 0}, {8, 12, 0}, {-8, 12, 0}};
                for (u32 i = 0; i < 4; ++i) {
                    const auto expected = origin + rotation * (localCenter + offsets[i]);
                    CHECK(std::abs(vertices[i].position.x - expected.x) < .002f);
                    CHECK(std::abs(vertices[i].position.y - expected.y) < .002f);
                }
                CHECK(system.getLayerData(entity)->edit_revision == revision);
            }
            resources.shutdown();
        }
    }
}

TEST_CASE("tilemaps: a layer that has not changed draws again without making or filling a buffer") {
    Harness h;
    RenderContext context(h.device);
    resource::ResourceManager resources;
    resources.init(h.device);
    const u8 pixels[16 * 16 * 4] = {};
    const auto texture = resources.createTexture(resource::ResourceContent::Retained, 16, 16, pixels, TextureFormat::RGBA8);
    ecs::Registry registry;
    const auto entity = registry.create();
    auto& transform = registry.emplace<ecs::Transform>(entity);
    auto& component = registry.emplace<ecs::TilemapLayer>(entity);
    component.tileset = texture; component.tilesetColumns = 1; component.cellSize = {16, 16};
    tilemap::TilemapSystem system;
    system.initLayer(entity, 64, 64, 16, 16);
    system.setTile(entity, 3, 3, 1);
    Frustum frustum;
    RenderFrameContext frameContext{context, resources};
    RenderCollectContext collect{registry, frustum, h.clips, h.pool, h.list, frameContext, {}};
    TilemapRenderPlugin plugin; plugin.setTilemapSystem(&system); plugin.init(frameContext);
    const auto projection = glm::ortho(0.0f, 200.0f, -200.0f, 0.0f);
    frustum.extractFromMatrix(projection); collect.camera = computeCameraView(projection);
    transform.worldPosition = {0, 0, 0}; transform.worldRotation = glm::quat{1, 0, 0, 0};
    transform.cachedMatrix_ = glm::mat4{1}; transform.decomposed_ = true;
    const auto frame = [&] { h.pool.beginFrame(); h.list.clear(); plugin.collect(collect); };

    frame();
    REQUIRE(h.list.commandCount() == 1);
    CHECK(h.list.command(0).hasPersistentGeometry());
    const int made = h.device.createBufferCalls;
    CHECK(made >= 2);  // a vertex and an index buffer

    // The same layer, drawn again: the same two buffers, nothing created and nothing uploaded through the frame's pool.
    for (int i = 0; i < 3; ++i) {
        frame();
        REQUIRE(h.list.commandCount() == 1);
        CHECK(h.device.createBufferCalls == made);
        CHECK(h.pool.vertexBytesUsed(LayoutId::Batch) == 0);
    }

    // A tile edited: the strip it is in is made again, once.
    system.setTile(entity, 4, 3, 1);
    frame();
    CHECK(h.device.createBufferCalls > made);
    const int afterEdit = h.device.createBufferCalls;
    frame();
    CHECK(h.device.createBufferCalls == afterEdit);

    // The layer moved: its tiles are somewhere else in the world, so the strip is made again.
    transform.worldPosition = {40, 0, 0};
    transform.cachedMatrix_ = glm::translate(glm::mat4{1}, glm::vec3{40, 0, 0});
    frame();
    CHECK(h.device.createBufferCalls > afterEdit);
    resources.shutdown();
}

TEST_CASE("tilemaps: a layer placed anew every frame is built per frame, and goes back to held geometry once it stands still") {
    Harness h;
    RenderContext context(h.device);
    resource::ResourceManager resources;
    resources.init(h.device);
    const u8 pixels[16 * 16 * 4] = {};
    const auto texture = resources.createTexture(resource::ResourceContent::Retained, 16, 16, pixels, TextureFormat::RGBA8);
    ecs::Registry registry;
    const auto entity = registry.create();
    auto& transform = registry.emplace<ecs::Transform>(entity);
    auto& component = registry.emplace<ecs::TilemapLayer>(entity);
    component.tileset = texture; component.tilesetColumns = 1; component.cellSize = {16, 16};
    tilemap::TilemapSystem system;
    system.initLayer(entity, 64, 64, 16, 16);
    system.setTile(entity, 3, 3, 1);
    Frustum frustum;
    RenderFrameContext frameContext{context, resources};
    RenderCollectContext collect{registry, frustum, h.clips, h.pool, h.list, frameContext, {}};
    TilemapRenderPlugin plugin; plugin.setTilemapSystem(&system); plugin.init(frameContext);
    const auto projection = glm::ortho(0.0f, 200.0f, -200.0f, 0.0f);
    frustum.extractFromMatrix(projection); collect.camera = computeCameraView(projection);
    transform.worldPosition = {0, 0, 0}; transform.worldRotation = glm::quat{1, 0, 0, 0};
    transform.cachedMatrix_ = glm::mat4{1}; transform.decomposed_ = true;
    const auto frame = [&] { h.pool.beginFrame(); h.list.clear(); plugin.collect(collect); };

    frame();
    REQUIRE(h.list.commandCount() == 1);
    CHECK(h.list.command(0).hasPersistentGeometry());

    // Faded a little more each frame: its tint is part of where it is placed, so it is placed anew every frame, and a strip is every chunk of a
    // row of them. It is built for the visible chunks into the frame's pool, as before, and makes no buffer of its own.
    frame();
    // Counted by what was made WITH contents: a strip's buffers are, and the frame's own streams (made when the pool is first written) are not.
    const usize made = h.device.createdBuffers.size();
    for (int i = 1; i <= 6; ++i) {
        component.opacity = 1.0f - 0.1f * static_cast<f32>(i);
        frame();
        REQUIRE(h.list.commandCount() == 1);
        CHECK(!h.list.command(0).hasPersistentGeometry());
        CHECK(h.device.createdBuffers.size() == made);
    }

    // Standing still for a while, it is held on the GPU again.
    for (int i = 0; i < 40; ++i) frame();
    REQUIRE(h.list.commandCount() == 1);
    CHECK(h.list.command(0).hasPersistentGeometry());
    resources.shutdown();
}

TEST_CASE("tilemaps: rows of chunks are drawn from the top row down, each a draw of its own") {
    Harness h;
    RenderContext context(h.device);
    resource::ResourceManager resources;
    resources.init(h.device);
    const u8 pixels[16 * 16 * 4] = {};
    const auto texture = resources.createTexture(resource::ResourceContent::Retained, 16, 16, pixels, TextureFormat::RGBA8);
    ecs::Registry registry;
    const auto entity = registry.create();
    auto& transform = registry.emplace<ecs::Transform>(entity);
    auto& component = registry.emplace<ecs::TilemapLayer>(entity);
    component.tileset = texture; component.tilesetColumns = 1; component.cellSize = {16, 16};
    tilemap::TilemapSystem system;
    system.initLayer(entity, 64, 64, 16, 16);
    // One tile in each of three chunk rows (a chunk is sixteen tiles tall), set last row first.
    system.setTile(entity, 1, 40, 1);
    system.setTile(entity, 1, 20, 1);
    system.setTile(entity, 1, 2, 1);
    Frustum frustum;
    RenderFrameContext frameContext{context, resources};
    RenderCollectContext collect{registry, frustum, h.clips, h.pool, h.list, frameContext, {}};
    TilemapRenderPlugin plugin; plugin.setTilemapSystem(&system); plugin.init(frameContext);
    const auto projection = glm::ortho(0.0f, 1100.0f, -1100.0f, 0.0f);
    frustum.extractFromMatrix(projection); collect.camera = computeCameraView(projection);
    transform.worldPosition = {0, 0, 0}; transform.worldRotation = glm::quat{1, 0, 0, 0};
    transform.cachedMatrix_ = glm::mat4{1}; transform.decomposed_ = true;
    h.pool.beginFrame(); h.list.clear(); h.device.createdBuffers.clear(); plugin.collect(collect);

    REQUIRE(h.list.commandCount() == 3);
    // The tile of chunk row 0 is the one nearest y = 0, and its draw is first: what the merged draw's order was.
    std::vector<f32> firstY;
    for (u32 i = 0; i < 3; ++i) {
        const u32 id = static_cast<u32>(h.list.command(i).vertex_buffer);
        const MockGfxDevice::CreatedBuffer* found = nullptr;
        for (const auto& made : h.device.createdBuffers) if (made.id == id) found = &made;
        REQUIRE(found != nullptr);
        firstY.push_back(reinterpret_cast<const BatchVertex*>(found->bytes.data())[0].position.y);
    }
    CHECK(firstY[0] > firstY[1]);
    CHECK(firstY[1] > firstY[2]);
    resources.shutdown();
}

TEST_CASE("tilemaps: a row being dug uploads the piece that changed, keeps its draw order, and is one strip again once it rests") {
    Harness h;
    RenderContext context(h.device);
    resource::ResourceManager resources;
    resources.init(h.device);
    const u8 pixels[16 * 16 * 4] = {};
    const auto texture = resources.createTexture(resource::ResourceContent::Retained, 16, 16, pixels, TextureFormat::RGBA8);
    ecs::Registry registry;
    const auto entity = registry.create();
    auto& transform = registry.emplace<ecs::Transform>(entity);
    auto& component = registry.emplace<ecs::TilemapLayer>(entity);
    component.tileset = texture; component.tilesetColumns = 1; component.cellSize = {16, 16};
    tilemap::TilemapSystem system;
    constexpr u32 ROW_TILES = 32 * 16 * 16;
    system.initLayer(entity, 32 * 16, 16, 16, 16);
    system.fillRect(entity, 0, 0, 32 * 16, 16, 1);
    Frustum frustum;
    RenderFrameContext frameContext{context, resources};
    RenderCollectContext collect{registry, frustum, h.clips, h.pool, h.list, frameContext, {}};
    TilemapRenderPlugin plugin; plugin.setTilemapSystem(&system); plugin.init(frameContext);
    const auto projection = glm::ortho(0.0f, 8300.0f, -300.0f, 0.0f);
    frustum.extractFromMatrix(projection); collect.camera = computeCameraView(projection);
    transform.worldPosition = {0, 0, 0}; transform.worldRotation = glm::quat{1, 0, 0, 0};
    transform.cachedMatrix_ = glm::mat4{1}; transform.decomposed_ = true;
    const auto frame = [&] { h.pool.beginFrame(); h.list.clear(); h.device.createdBuffers.clear(); plugin.collect(collect); };
    const auto indices = [&] {
        u32 total = 0;
        for (u32 i = 0; i < h.list.commandCount(); ++i) total += h.list.command(i).index_count;
        return total;
    };
    const auto vertexBytes = [&] {
        usize total = 0;
        for (const auto& made : h.device.createdBuffers) if (made.desc.usage == GfxBufferUsage::Vertex) total += made.bytes.size();
        return total;
    };

    frame();
    REQUIRE(h.list.commandCount() == 1);
    const usize wholeRow = vertexBytes();
    CHECK(indices() == ROW_TILES * 6);

    // The first tile dug cuts the row, so that one uploads all of it, and every piece is drawn left to right.
    system.setTile(entity, 5 * 16 + 3, 3, 0);
    frame();
    REQUIRE(h.list.commandCount() == 8);
    CHECK(indices() == (ROW_TILES - 1) * 6);
    std::vector<f32> firstX;
    for (u32 i = 0; i < 8; ++i) {
        const u32 id = static_cast<u32>(h.list.command(i).vertex_buffer);
        const MockGfxDevice::CreatedBuffer* found = nullptr;
        for (const auto& made : h.device.createdBuffers) if (made.id == id) found = &made;
        REQUIRE(found != nullptr);
        firstX.push_back(reinterpret_cast<const BatchVertex*>(found->bytes.data())[0].position.x);
    }
    CHECK(std::is_sorted(firstX.begin(), firstX.end()));

    // Every tile after it uploads one piece: an eighth of the row, a vertex and an index buffer.
    system.setTile(entity, 5 * 16 + 4, 3, 0);
    frame();
    CHECK(h.device.createdBuffers.size() == 2);
    CHECK(vertexBytes() < wholeRow / 8);
    CHECK(vertexBytes() > wholeRow / 16);
    CHECK(indices() == (ROW_TILES - 2) * 6);

    // A frame with no change uploads nothing, pieces or not.
    frame();
    CHECK(h.device.createdBuffers.empty());
    CHECK(h.list.commandCount() == 8);

    // At rest the row goes back to one draw, once, and holds still.
    bool rejoined = false;
    for (int i = 0; i < 4000 && !rejoined; ++i) { frame(); rejoined = h.list.commandCount() == 1; }
    REQUIRE(rejoined);
    CHECK(indices() == (ROW_TILES - 2) * 6);
    frame();
    CHECK(h.device.createdBuffers.empty());
    resources.shutdown();
}

TEST_CASE("appendQuad: Batch command with baseVertex-offset indices and one texture slot") {
    Harness h;
    BatchVertex quad[4] = {
        { {0, 0, 0}, 0xFFFFFFFFu, {0, 0} },
        { {1, 0, 0}, 0xFFFFFFFFu, {1, 0} },
        { {1, 1, 0}, 0xFFFFFFFFu, {1, 1} },
        { {0, 1, 0}, 0xFFFFFFFFu, {0, 1} },
    };
    appendQuad(h.pool, h.list, h.clips, quad, quadKey(42));
    appendQuad(h.pool, h.list, h.clips, quad, quadKey(42));

    REQUIRE(h.list.commandCount() == 2);
    const DrawCommand& first = h.list.command(0);
    const DrawCommand& second = h.list.command(1);
    CHECK(first.layout_id == LayoutId::Batch);
    CHECK(first.index_count == 6);
    CHECK(first.vertex_count == 4);
    CHECK(first.texture_count == 1);
    CHECK(first.texture_ids[0] == 42);
    CHECK(first.instance_count == 0);
    // Second quad's vertices start at record 4, so its indices must be rebased there.
    CHECK(second.vertex_byte_offset == 4 * sizeof(BatchVertex));
    CHECK(second.index_offset == 6);
}

TEST_CASE("empty scissor regions allocate no quad geometry or draw command") {
    for (const auto size : {std::pair{0, 20}, std::pair{20, 0}, std::pair{-1, 20}}) {
        Harness h;
        BatchVertex quad[4] = {};
        auto blocked = quadKey(42); blocked.entity = Entity(91);
        h.clips.setScissor(91, 10, 20, size.first, size.second);
        h.clips.setStencilTestOutside(91, 3);
        appendQuad(h.pool, h.list, h.clips, quad, blocked);
        auto visible = quadKey(42); visible.entity = Entity(92);
        appendQuad(h.pool, h.list, h.clips, quad, visible);
        REQUIRE(h.list.commandCount() == 1);
        CHECK(h.list.command(0).entity == Entity(92));
        CHECK(h.list.command(0).vertex_byte_offset == 0);
        CHECK(h.list.command(0).index_offset == 0);
    }
}

TEST_CASE("empty scissors suppress direct and prebuilt-vertex submissions") {
    Harness h;
    auto blocked = quadKey(42); blocked.entity = Entity(91);
    h.clips.setScissor(91, 0, 0, 0, 0);
    pushBatchDraw(h.list, h.clips, 0, 4, 0, 6, blocked);
    const u32 indices[] = {0, 1, 2, 2, 3, 0};
    pushBatchCommand(h.pool, h.list, h.clips, 0, 4, indices, 6, blocked);
    CHECK(h.list.commandCount() == 0);
    BatchVertex quad[4] = {};
    auto visible = quadKey(42); visible.entity = Entity(92);
    appendQuad(h.pool, h.list, h.clips, quad, visible);
    REQUIRE(h.list.commandCount() == 1);
    CHECK(h.list.command(0).index_offset == 0);
}

TEST_CASE("stencil-only entries and nonempty scissors still draw") {
    Harness h;
    BatchVertex quad[4] = {};
    auto stencil = quadKey(42); stencil.entity = Entity(91);
    h.clips.setStencilMask(91, 1);
    appendQuad(h.pool, h.list, h.clips, quad, stencil);
    auto clipped = quadKey(42); clipped.entity = Entity(92);
    h.clips.setScissor(92, 10, 20, 1, 1);
    appendQuad(h.pool, h.list, h.clips, quad, clipped);
    CHECK(h.list.commandCount() == 2);
}

TEST_CASE("appendIndexedDraw: non-Batch stream uses its own stride for baseVertex") {
    Harness h;
    TestShapeVertex verts[4] = {};
    BatchDrawKey key = quadKey(0);
    key.type = RenderType::Shape;
    key.layoutId = LayoutId::Shape;

    appendIndexedDraw(h.pool, h.list, h.clips, verts, 4, BATCH_QUAD_INDICES, 6, key);
    appendIndexedDraw(h.pool, h.list, h.clips, verts, 4, BATCH_QUAD_INDICES, 6, key);

    REQUIRE(h.list.commandCount() == 2);
    CHECK(h.list.command(0).layout_id == LayoutId::Shape);
    // A textureless draw must not claim a sampler slot: texture_count is what
    // execute() binds, and zero of them is what "declares no sampler" looks like.
    CHECK(h.list.command(0).texture_count == 0);
    CHECK(h.list.command(1).vertex_byte_offset == 4 * sizeof(TestShapeVertex));
    // Indices rebased by the SHAPE stride (4 records), not the Batch stride.
    CHECK(h.list.command(1).index_offset == 6);
    CHECK(h.pool.vertexBytesUsed(LayoutId::Shape) == 8 * sizeof(TestShapeVertex));
    CHECK(h.pool.indicesUsed(LayoutId::Shape) == 12);
}

TEST_CASE("pushBatchDraw: instanced key assembles an instanced command over static indices") {
    Harness h;
    u32 instOffset = h.pool.allocVertices(LayoutId::ParticleInstance, 3 * 40);
    BatchDrawKey key = quadKey(42);  // type tag irrelevant here (stats/capture only)
    key.layoutId = LayoutId::ParticleInstance;
    key.instanceCount = 3;

    pushBatchDraw(h.list, h.clips, instOffset, 0, 0, 6, key);

    REQUIRE(h.list.commandCount() == 1);
    const DrawCommand& cmd = h.list.command(0);
    CHECK(cmd.layout_id == LayoutId::ParticleInstance);
    CHECK(cmd.instance_count == 3);
    CHECK(cmd.index_offset == 0);
    CHECK(cmd.index_count == 6);
    CHECK(cmd.texture_count == 1);
    CHECK(cmd.texture_ids[0] == 42);
}

TEST_CASE("finalize: adjacent same-key Batch draws with different textures merge multi-texture") {
    Harness h;
    BatchVertex quad[4] = {
        { {0, 0, 0}, 0xFFFFFFFFu, {0, 0} },
        { {1, 0, 0}, 0xFFFFFFFFu, {1, 0} },
        { {1, 1, 0}, 0xFFFFFFFFu, {1, 1} },
        { {0, 1, 0}, 0xFFFFFFFFu, {0, 1} },
    };
    appendQuad(h.pool, h.list, h.clips, quad, quadKey(42));
    appendQuad(h.pool, h.list, h.clips, quad, quadKey(43));

    h.list.finalize(h.pool);

    REQUIRE(h.list.mergedDrawCallCount() == 1);
    const DrawCommand& merged = h.list.command(0);
    CHECK(merged.index_count == 12);
    CHECK(merged.texture_count == 2);
    CHECK(merged.texture_ids[0] == 42);
    CHECK(merged.texture_ids[1] == 43);
    // The second quad's staged vertices got their sampler slot stamped to 1.
    const auto* verts = reinterpret_cast<const BatchVertex*>(h.pool.vertexData(LayoutId::Batch));
    CHECK(verts[3].texIndex == 0.0f);
    CHECK(verts[4].texIndex == 1.0f);
    CHECK(verts[7].texIndex == 1.0f);
}

TEST_CASE("finalize: material draws with different textures stay apart, the same texture still merges") {
    // A material's shader samples the sprite at slot 0 alone, so a merged run that
    // gave the second sprite slot 1 drew it with the first sprite's picture.
    Harness h;
    BatchVertex quad[4] = {
        { {0, 0, 0}, 0xFFFFFFFFu, {0, 0} },
        { {1, 0, 0}, 0xFFFFFFFFu, {1, 0} },
        { {1, 1, 0}, 0xFFFFFFFFu, {1, 1} },
        { {0, 1, 0}, 0xFFFFFFFFu, {0, 1} },
    };
    BatchDrawKey a = quadKey(42);
    a.materialId = 7;
    BatchDrawKey b = quadKey(43);
    b.materialId = 7;
    appendQuad(h.pool, h.list, h.clips, quad, a);
    appendQuad(h.pool, h.list, h.clips, quad, a);
    appendQuad(h.pool, h.list, h.clips, quad, b);

    h.list.finalize(h.pool);

    REQUIRE(h.list.mergedDrawCallCount() == 2);
    CHECK(h.list.command(0).texture_count == 1);
    CHECK(h.list.command(0).texture_ids[0] == 42);
    CHECK(h.list.command(0).index_count == 12);
    CHECK(h.list.command(1).texture_ids[0] == 43);
    CHECK(h.list.command(1).break_reason == BatchBreak::TextureSlots);
    const auto* verts = reinterpret_cast<const BatchVertex*>(h.pool.vertexData(LayoutId::Batch));
    CHECK(verts[8].texIndex == 0.0f);
}

TEST_CASE("finalize: a frame with the same keys as the last takes its order, a frame with other keys is sorted again") {
    Harness h;
    BatchVertex quad[4] = {};
    // Layers say the order, textures say which draw is which: what a frame draws is read back from the merged draw's slots.
    const auto frame = [&](const i32 (&layers)[3], const u32 (&textures)[3]) {
        h.list.clear();
        h.pool.beginFrame();
        for (int i = 0; i < 3; ++i) appendQuad(h.pool, h.list, h.clips, quad, quadKey(textures[i], layers[i]));
        h.list.finalize(h.pool);
        REQUIRE(h.list.mergedDrawCallCount() == 1);
        return h.list.command(0);
    };
    const DrawCommand first = frame({3, 1, 2}, {10, 11, 12});
    CHECK((std::vector<u32>{first.texture_ids[0], first.texture_ids[1], first.texture_ids[2]} == std::vector<u32>{11, 12, 10}));
    // The same layers, so the same order, over other draws.
    const DrawCommand same = frame({3, 1, 2}, {20, 21, 22});
    CHECK((std::vector<u32>{same.texture_ids[0], same.texture_ids[1], same.texture_ids[2]} == std::vector<u32>{21, 22, 20}));
    // Other layers: the order of the frame before is not the order of this one.
    const DrawCommand other = frame({1, 3, 2}, {30, 31, 32});
    CHECK((std::vector<u32>{other.texture_ids[0], other.texture_ids[1], other.texture_ids[2]} == std::vector<u32>{30, 32, 31}));
    // And back to the first keys again, from a list that last sorted something else.
    const DrawCommand back = frame({3, 1, 2}, {40, 41, 42});
    CHECK((std::vector<u32>{back.texture_ids[0], back.texture_ids[1], back.texture_ids[2]} == std::vector<u32>{41, 42, 40}));
}

TEST_CASE("finalize: sorted Batch index gaps merge in painter order with their texture slots") {
    Harness h;
    BatchVertex quad[4] = {};
    appendQuad(h.pool, h.list, h.clips, quad, quadKey(10, 3));
    appendQuad(h.pool, h.list, h.clips, quad, quadKey(11, 1));
    appendQuad(h.pool, h.list, h.clips, quad, quadKey(12, 2));
    h.list.finalize(h.pool);
    REQUIRE(h.list.mergedDrawCallCount() == 1);
    const auto& cmd = h.list.command(0);
    REQUIRE(cmd.index_count == 18);
    const u32 expected[] = {4,5,6,6,7,4, 8,9,10,10,11,8, 0,1,2,2,3,0};
    const auto* indices = h.pool.indexData(LayoutId::Batch) + cmd.index_offset;
    for (u32 i = 0; i < 18; i++) CHECK(indices[i] == expected[i]);
    REQUIRE(cmd.texture_count == 3);
    CHECK(cmd.texture_ids[0] == 11);
    CHECK(cmd.texture_ids[1] == 12);
    CHECK(cmd.texture_ids[2] == 10);
    const auto* verts = reinterpret_cast<const BatchVertex*>(h.pool.vertexData(LayoutId::Batch));
    CHECK(verts[0].texIndex == 2);
    CHECK(verts[4].texIndex == 0);
    CHECK(verts[8].texIndex == 1);
}

TEST_CASE("camera mask: hidden text and skeletal submissions upload no geometry") {
    MockGfxDevice device;
    RenderContext context(device);
    resource::ResourceManager resources;
    RenderFrame frame(device, context, resources);
    frame.init(64, 64);
    const glm::mat4 transform(1.0f);
    const f32 text[36] = {};
    const f32 skeletal[32] = {};
    const u16 indices[] = {0, 1, 2, 2, 3, 0};
    frame.begin(transform);
    frame.setCullingMask(1u << 6);
    const int uploads = device.updateBufferCalls;
    for (u32 i = 0; i < 1000; ++i) {
        frame.submitTextBatch(text, 4, indices, 6, 1, &transform[0][0], Entity(1), 4, 0, TextGlyphMode::Color);
        frame.submitSkeletalBatch(skeletal, 4, indices, 6, 1, 0, &transform[0][0], Entity(2), 4, 0, 0, false);
    }
    frame.flush();
    CHECK(frame.stats().draw_calls == 0);
    CHECK(device.updateBufferCalls == uploads);
    frame.end();
    frame.begin(transform);
    frame.setCullingMask(1u << 6);
    frame.submitTextBatch(text, 4, indices, 6, 1, &transform[0][0], Entity(1), 4, 0, TextGlyphMode::Color, 1u << 6);
    frame.submitSkeletalBatch(skeletal, 4, indices, 6, 1, 0, &transform[0][0], Entity(2), 6, 0, 0, false);
    frame.flush();
    CHECK(frame.stats().sprites == 0);
    CHECK(frame.stats().text == 1);
    CHECK(frame.stats().skeletal == 1);
    CHECK(frame.stats().triangles == 4);
}

TEST_CASE("sprites: affine parents preserve every draw mode and mirrored tile grid") {
    for (auto mode : {ecs::SpriteDrawMode::Simple, ecs::SpriteDrawMode::NineSlice, ecs::SpriteDrawMode::Tiled}) {
        for (bool parented : {false, true}) for (bool mirror : {false, true}) for (bool capped : {false, true}) {
            if (capped && mode != ecs::SpriteDrawMode::Tiled) continue;
            Harness h;
            RenderContext context(h.device);
            resource::ResourceManager resources;
            resources.init(h.device);
            const u8 pixels[16 * 16 * 4] = {};
            const auto texture = resources.createTexture(resource::ResourceContent::Retained, 16, 16,
                                                         pixels, TextureFormat::RGBA8);
            resource::TextureMetadata metadata;
            metadata.sliceBorder = {2, 2, 2, 2};
            resources.setTextureMetadata(texture, metadata);
            ecs::Registry registry;
            const auto parent = registry.create(), entity = registry.create();
            if (parented) registry.emplace<ecs::Parent>(entity).entity = parent;
            auto& transform = registry.emplace<ecs::Transform>(entity);
            const auto matrix = glm::scale(glm::mat4(1), glm::vec3(parented ? 2 : 1, 1, 1))
                                    * glm::translate(glm::mat4(1), glm::vec3(4, -7, 0))
                                    * glm::mat4_cast(glm::angleAxis(.7f, glm::vec3(0, 0, 1)))
                                    * glm::scale(glm::mat4(1), glm::vec3(mirror ? -3 : 3, 2, 1));
            if (parented) {
                transform.cachedMatrix_ = matrix;
                transform.decomposed_ = false;
            } else {
                // Childless roots intentionally leave cachedMatrix_ untouched.
                transform.worldPosition = {4, -7, 0};
                transform.worldRotation = glm::angleAxis(.7f, glm::vec3(0, 0, 1));
                transform.worldScale = {mirror ? -3 : 3, 2, 1};
                transform.decomposed_ = true;
            }
            auto& sprite = registry.emplace<ecs::Sprite>(entity);
            sprite.texture = texture;
            sprite.size = {20, 30};
            sprite.pivot = {.25f, .75f};
            sprite.tileSize = capped ? glm::vec2(.01f) : glm::vec2(4, 5);
            sprite.drawMode = mode;
            Frustum frustum;
            frustum.extractFromMatrix(glm::ortho(-500.0f, 500.0f, -500.0f, 500.0f));
            RenderFrameContext frameContext{context, resources};
            RenderCollectContext collect{registry, frustum, h.clips, h.pool, h.list, frameContext, {}};
            SpritePlugin plugin;
            plugin.init(frameContext);
            plugin.collect(collect);
            const auto* vertices = reinterpret_cast<const BatchVertex*>(h.pool.vertexData(LayoutId::Batch));
            const u32 count = h.pool.vertexBytesUsed(LayoutId::Batch) / sizeof(BatchVertex);
            CHECK(count > 0);
            const auto inverse = glm::inverse(matrix);
            f32 area = 0;
            for (u32 i = 0; i < count; ++i) {
                const auto local = glm::vec3(inverse * glm::vec4(vertices[i].position, 1));
                CHECK(local.x >= -5.001f);
                CHECK(local.x <= 15.001f);
                CHECK(local.y >= -22.501f);
                CHECK(local.y <= 7.501f);
                if (i % 4 == 0) {
                    const auto a = vertices[i+1].position - vertices[i].position;
                    const auto b = vertices[i+3].position - vertices[i].position;
                    area += std::abs(a.x * b.y - a.y * b.x);
                }
            }
            CHECK(area == doctest::Approx(parented ? 7200 : 3600).epsilon(.0001));
            // A camera touching the actual transformed corner must not cull it.
            const auto corner = glm::vec3(matrix * glm::vec4(-5, -22.5f, 0, 1));
            frustum.extractFromMatrix(glm::ortho(corner.x - .1f, corner.x + .1f,
                                                corner.y - .1f, corner.y + .1f));
            h.pool.beginFrame();
            h.list.clear();
            plugin.collect(collect);
            CHECK(h.pool.vertexBytesUsed(LayoutId::Batch) > 0);
            for (auto zeroAxis : {0, 1}) {
                sprite.size[zeroAxis] = 0;
                h.pool.beginFrame();
                h.list.clear();
                plugin.collect(collect);
                CHECK(h.pool.vertexBytesUsed(LayoutId::Batch) == 0);
                sprite.size = {20, 30};
            }
            resources.shutdown();
        }
    }
}

TEST_CASE("sprites: a pivot outside 0..1 puts the box where the pivot says, in every draw mode") {
    // Pivot (-0.5, -0.25) puts the origin half a width left of, and a quarter-height below, the box: the box spans
    // [-pivot*size, (1-pivot)*size] about the origin, i.e. x in [10, 30], y in [7.5, 37.5] for a 20x30 sprite.
    const glm::vec2 pivots[] = {{-.5f, -.25f}, {1.5f, 1.25f}, {-1.f, 2.f}};
    for (auto mode : {ecs::SpriteDrawMode::Simple, ecs::SpriteDrawMode::NineSlice, ecs::SpriteDrawMode::Tiled}) {
        for (f32 angle : {0.0f, .7f}) for (const auto pivot : pivots) {
            Harness h;
            RenderContext context(h.device);
            resource::ResourceManager resources;
            resources.init(h.device);
            const u8 pixels[16 * 16 * 4] = {};
            const auto texture = resources.createTexture(resource::ResourceContent::Retained, 16, 16,
                                                         pixels, TextureFormat::RGBA8);
            resource::TextureMetadata metadata;
            metadata.sliceBorder = {2, 2, 2, 2};
            resources.setTextureMetadata(texture, metadata);
            ecs::Registry registry;
            const auto entity = registry.create();
            auto& transform = registry.emplace<ecs::Transform>(entity);
            transform.worldPosition = {40, -60, 0};
            transform.worldRotation = glm::angleAxis(angle, glm::vec3(0, 0, 1));
            transform.worldScale = {1, 1, 1};
            transform.decomposed_ = true;
            auto& sprite = registry.emplace<ecs::Sprite>(entity);
            sprite.texture = texture;
            sprite.size = {20, 30};
            sprite.pivot = pivot;
            sprite.tileSize = {4, 5};
            sprite.drawMode = mode;
            Frustum frustum;
            frustum.extractFromMatrix(glm::ortho(-500.0f, 500.0f, -500.0f, 500.0f));
            RenderFrameContext frameContext{context, resources};
            RenderCollectContext collect{registry, frustum, h.clips, h.pool, h.list, frameContext, {}};
            SpritePlugin plugin;
            plugin.init(frameContext);
            plugin.collect(collect);
            const auto* vertices = reinterpret_cast<const BatchVertex*>(h.pool.vertexData(LayoutId::Batch));
            const u32 count = h.pool.vertexBytesUsed(LayoutId::Batch) / sizeof(BatchVertex);
            REQUIRE(count > 0);
            const auto inverse = glm::inverse(glm::translate(glm::mat4(1), glm::vec3(40, -60, 0))
                                              * glm::mat4_cast(transform.worldRotation));
            glm::vec2 low{1e9f}, high{-1e9f};
            for (u32 i = 0; i < count; ++i) {
                const auto local = glm::vec2(inverse * glm::vec4(vertices[i].position, 1));
                low = glm::min(low, local);
                high = glm::max(high, local);
            }
            INFO("mode ", int(mode), " angle ", angle, " pivot ", pivot.x, ",", pivot.y);
            CHECK(low.x == doctest::Approx(-pivot.x * 20).epsilon(.0001));
            CHECK(low.y == doctest::Approx(-pivot.y * 30).epsilon(.0001));
            CHECK(high.x == doctest::Approx((1 - pivot.x) * 20).epsilon(.0001));
            CHECK(high.y == doctest::Approx((1 - pivot.y) * 30).epsilon(.0001));
            resources.shutdown();
        }
    }
}

TEST_CASE("UI visuals: affine parents preserve box-local geometry and fill edges") {
    for (auto type : {ecs::UIVisualType::SolidColor, ecs::UIVisualType::Image,
                      ecs::UIVisualType::NineSlice, ecs::UIVisualType::Tiled, ecs::UIVisualType::Filled}) {
        for (bool mirror : {false, true}) for (bool radial : {false, true}) {
            if (radial && type != ecs::UIVisualType::Filled) continue;
            Harness h;
            RenderContext context(h.device);
            resource::ResourceManager resources;
            resources.init(h.device);
            const u8 pixels[16 * 16 * 4] = {};
            const auto texture = resources.createTexture(resource::ResourceContent::Retained,
                                                         16, 16, pixels, TextureFormat::RGBA8);
            ecs::Registry registry;
            const auto parent = registry.create(), entity = registry.create();
            registry.emplace<ecs::Parent>(entity).entity = parent;
            auto& transform = registry.emplace<ecs::Transform>(entity);
            transform.cachedMatrix_ = glm::scale(glm::mat4(1), glm::vec3(2, 1, 1))
                                    * glm::translate(glm::mat4(1), glm::vec3(4, -7, 0))
                                    * glm::mat4_cast(glm::angleAxis(.7f, glm::vec3(0, 0, 1)))
                                    * glm::scale(glm::mat4(1), glm::vec3(mirror ? -3 : 3, 2, 1));
            transform.decomposed_ = false;
            registry.emplace<ecs::UINode>(entity).computed_size_ = {20, 30};
            auto& visual = registry.emplace<ecs::UIVisual>(entity);
            visual.texture = texture;
            visual.visualType = type;
            visual.sliceBorder = {2, 2, 2, 2};
            visual.fillAmount = .5f;
            visual.fillMethod = radial ? ecs::UIFillMethod::Radial360 : ecs::UIFillMethod::Horizontal;
            visual.fillOrigin = radial ? ecs::UIFillOrigin::Top : ecs::UIFillOrigin::Left;
            Frustum frustum;
            frustum.extractFromMatrix(glm::ortho(-500.0f, 500.0f, -500.0f, 500.0f));
            RenderFrameContext frameContext{context, resources};
            RenderCollectContext collect{registry, frustum, h.clips, h.pool, h.list, frameContext, {}};
            UIElementPlugin plugin;
            plugin.init(frameContext);
            plugin.collect(collect);
            const u32 count = h.pool.vertexBytesUsed(LayoutId::Batch) / sizeof(BatchVertex);
            CHECK(count > 0);
            const auto* vertices = reinterpret_cast<const BatchVertex*>(h.pool.vertexData(LayoutId::Batch));
            const auto inverse = glm::inverse(transform.cachedMatrix_);
            for (u32 i = 0; i < count; ++i) {
                const auto local = glm::vec3(inverse * glm::vec4(vertices[i].position, 1));
                CHECK(local.x >= -10.001f);
                CHECK(local.x <= 10.001f);
                CHECK(local.y >= -15.001f);
                CHECK(local.y <= 15.001f);
                if (type == ecs::UIVisualType::Filled) {
                    if (radial) CHECK(local.x >= -.001f);
                    else CHECK(local.x <= .001f);
                }
            }
            const auto corner = glm::vec3(transform.cachedMatrix_ * glm::vec4(-10, 15, 0, 1));
            frustum.extractFromMatrix(glm::ortho(corner.x-.1f, corner.x+.1f, corner.y-.1f, corner.y+.1f));
            h.pool.beginFrame();
            h.list.clear();
            plugin.collect(collect);
            CHECK(h.pool.vertexBytesUsed(LayoutId::Batch) > 0);
            resources.shutdown();
        }
    }
}

TEST_CASE("radial fills: signed boxes mirror positions while retaining sampled UVs") {
    for (f32 x : {1.0f, -1.0f}) for (f32 y : {1.0f, -1.0f}) {
        Harness original, reflected;
        NineSlicePlugin plugin;
        const glm::vec3 center{13, 17, 0};
        plugin.emitRadialFill(original.pool, original.list, original.clips,
                             center, {20, 30}, 0, 1.5707963f, 3.1415927f,
                             {.2f, .3f}, {.4f, .5f}, {1, 1, 1, 1}, quadKey(1));
        plugin.emitRadialFill(reflected.pool, reflected.list, reflected.clips,
                             center, {20*x, 30*y}, 0, 1.5707963f, 3.1415927f,
                             {.2f, .3f}, {.4f, .5f}, {1, 1, 1, 1}, quadKey(1));
        REQUIRE(original.pool.vertexBytesUsed(LayoutId::Batch) > 0);
        REQUIRE(reflected.pool.vertexBytesUsed(LayoutId::Batch) == original.pool.vertexBytesUsed(LayoutId::Batch));
        const auto* a = reinterpret_cast<const BatchVertex*>(original.pool.vertexData(LayoutId::Batch));
        const auto* b = reinterpret_cast<const BatchVertex*>(reflected.pool.vertexData(LayoutId::Batch));
        for (u32 i = 0; i < original.pool.vertexBytesUsed(LayoutId::Batch) / sizeof(BatchVertex); ++i) {
            CHECK(b[i].position.x == doctest::Approx(center.x + (a[i].position.x-center.x)*x));
            CHECK(b[i].position.y == doctest::Approx(center.y + (a[i].position.y-center.y)*y));
            CHECK(b[i].texCoord == a[i].texCoord);
        }
    }
}

TEST_CASE("UI and sprite picking: parent shear follows authored local bounds") {
    for (bool uiNode : {false, true}) for (bool mirror : {false, true}) {
        ecs::Registry registry;
        const auto parent = registry.create(), entity = registry.create();
        registry.emplace<ecs::Canvas>(parent);
        registry.emplace<ecs::Transform>(parent);
        registry.emplace<ecs::UINode>(parent).computed_size_ = {200, 200};
        registry.emplace<ecs::Children>(parent).entities.push_back(entity);
        registry.emplace<ecs::Parent>(entity).entity = parent;
        auto& transform = registry.emplace<ecs::Transform>(entity);
        transform.cachedMatrix_ = glm::scale(glm::mat4(1), glm::vec3(2, 1, 1))
                                * glm::translate(glm::mat4(1), glm::vec3(4, -7, 0))
                                * glm::mat4_cast(glm::angleAxis(.7f, glm::vec3(0, 0, 1)))
                                * glm::scale(glm::mat4(1), glm::vec3(mirror ? -3 : 3, 2, 1));
        transform.decomposed_ = false;
        registry.emplace<ecs::Interactable>(entity);
        if (uiNode) registry.emplace<ecs::UINode>(entity).computed_size_ = {20, 30};
        else registry.emplace<ecs::Sprite>(entity).size = {20, 30};
        ecs::UISystem ui;
        ui.tree.rebuild(registry);
        for (const glm::vec2 local : {glm::vec2(9, 14), {-9, -14}, {11, 0}, {0, 16}}) {
            const auto point = glm::vec3(transform.cachedMatrix_ * glm::vec4(local, 0, 1));
            const bool inside = std::abs(local.x) < 10 && std::abs(local.y) < 15;
            ui.hitTestUpdate(registry, ecs::PickRay{{point.x, point.y, 100}, {0, 0, -1}}, nullptr);
            CHECK((ui.hitResult.hit_entity == entity) == inside);
            if (uiNode) CHECK((ui.pick(registry, point.x, point.y) == entity.id()) == inside);
        }
        const auto child = registry.create();
        registry.emplace<ecs::Parent>(child).entity = entity;
        if (!uiNode) registry.emplace<ecs::UINode>(entity).computed_size_ = {20, 30};
        registry.emplace<ecs::UIMask>(entity);
        for (const glm::vec2 local : {glm::vec2(9, 14), {-9, -14}, {11, 0}, {0, 16}}) {
            const auto point = glm::vec3(transform.cachedMatrix_ * glm::vec4(local, 0, 1));
            CHECK(ecs::isClippedByMask(registry, child, point.x, point.y)
                  == (std::abs(local.x) > 10 || std::abs(local.y) > 15));
        }
    }
}

TEST_CASE("UI scissor: affine corners determine the projected clip rectangle") {
    MockGfxDevice device;
    RenderContext context(device);
    resource::ResourceManager resources;
    ecs::Registry registry;
    RenderFrame frame(device, context, resources);
    frame.init(200, 200);
    const auto parent = registry.create(), mask = registry.create(), child = registry.create();
    registry.emplace<ecs::Parent>(mask).entity = parent;
    registry.emplace<ecs::Children>(mask).entities.push_back(child);
    registry.emplace<ecs::Parent>(child).entity = mask;
    auto& transform = registry.emplace<ecs::Transform>(mask);
    transform.cachedMatrix_ = glm::scale(glm::mat4(1), glm::vec3(2, 1, 1))
                            * glm::mat4_cast(glm::angleAxis(.7f, glm::vec3(0, 0, 1)));
    transform.decomposed_ = false;
    registry.emplace<ecs::UINode>(mask).computed_size_ = {20, 30};
    registry.emplace<ecs::UIMask>(mask).mode = ecs::MaskMode::Scissor;
    const auto half = glm::abs(glm::vec3(transform.cachedMatrix_[0])) * 10.0f
                    + glm::abs(glm::vec3(transform.cachedMatrix_[1])) * 15.0f;
    const std::array<i32, 4> expected{static_cast<i32>(std::round(100-half.x)),
                                     static_cast<i32>(std::round(100-half.y)),
                                     static_cast<i32>(std::round(2*half.x)),
                                     static_cast<i32>(std::round(2*half.y))};
    const f32 vertices[36] = {};
    const u16 indices[] = {0, 1, 2, 2, 3, 0};
    const glm::mat4 identity(1);
    frame.beginFrame();
    frame.begin(glm::ortho(-100.0f, 100.0f, -100.0f, 100.0f));
    frame.processMasks(registry, 0, 0, 200, 200);
    frame.collectAll(registry);
    frame.submitTextBatch(vertices, 4, indices, 6, 1, &identity[0][0], child, 0, 0, TextGlyphMode::Color);
    frame.flush();
    frame.end();
    CHECK(std::find(device.scissorRectangles.begin(), device.scissorRectangles.end(), expected)
          != device.scissorRectangles.end());
    frame.endFrame();
}

TEST_CASE("UI scissor: a ContentRect gives world content a clip box, about its pivot") {
    struct Case { glm::vec2 pivot; std::array<i32, 4> expected; };
    // The entity stands at the world origin, which the orthographic view puts at pixel (100, 100). A 20 x 30 rectangle hangs from its
    // pivot: pivot (0,0) reaches right and up from the origin; pivot (0.5,0.5) is centred on it; pivot (1,1) reaches left and down.
    const Case cases[] = {
        {{0.0f, 0.0f}, {100, 100, 20, 30}},
        {{0.5f, 0.5f}, {90, 85, 20, 30}},
        {{1.0f, 1.0f}, {80, 70, 20, 30}},
    };
    for (const auto& c : cases) {
        MockGfxDevice device;
        RenderContext context(device);
        resource::ResourceManager resources;
        ecs::Registry registry;
        RenderFrame frame(device, context, resources);
        frame.init(200, 200);
        const auto mask = registry.create(), child = registry.create();
        registry.emplace<ecs::Children>(mask).entities.push_back(child);
        registry.emplace<ecs::Parent>(child).entity = mask;
        registry.emplace<ecs::Transform>(mask);
        auto& rect = registry.emplace<ecs::ContentRect>(mask);
        rect.size = {20, 30};
        rect.pivot = c.pivot;
        registry.emplace<ecs::UIMask>(mask).mode = ecs::MaskMode::Scissor;
        const f32 vertices[36] = {};
        const u16 indices[] = {0, 1, 2, 2, 3, 0};
        const glm::mat4 identity(1);
        frame.beginFrame();
        frame.begin(glm::ortho(-100.0f, 100.0f, -100.0f, 100.0f));
        frame.processMasks(registry, 0, 0, 200, 200);
        frame.collectAll(registry);
        frame.submitTextBatch(vertices, 4, indices, 6, 1, &identity[0][0], child, 0, 0, TextGlyphMode::Color);
        frame.flush();
        frame.end();
        CHECK(std::find(device.scissorRectangles.begin(), device.scissorRectangles.end(), c.expected)
              != device.scissorRectangles.end());
        frame.endFrame();
    }
}

TEST_CASE("flat geometry: collapsed parent bases skip uploads and recover") {
    for (bool ui : {false, true}) {
        for (u32 mode = 0; mode < (ui ? 5u : 3u); ++mode) {
            Harness h;
            RenderContext context(h.device);
            resource::ResourceManager resources;
            resources.init(h.device);
            const u8 pixels[16 * 16 * 4] = {};
            const auto texture = resources.createTexture(resource::ResourceContent::Retained,
                                                         16, 16, pixels, TextureFormat::RGBA8);
            resource::TextureMetadata metadata;
            metadata.sliceBorder = {2, 2, 2, 2};
            resources.setTextureMetadata(texture, metadata);
            ecs::Registry registry;
            const auto parent = registry.create(), entity = registry.create();
            registry.emplace<ecs::Parent>(entity).entity = parent;
            auto& transform = registry.emplace<ecs::Transform>(entity);
            transform.cachedMatrix_[0] = {1, 1, 0, 0};
            transform.cachedMatrix_[1] = {.5f, .5f, 0, 0};
            if (ui) {
                registry.emplace<ecs::UINode>(entity).computed_size_ = {20, 30};
                auto& visual = registry.emplace<ecs::UIVisual>(entity);
                visual.texture = texture;
                visual.visualType = static_cast<ecs::UIVisualType>(mode + 1);
                visual.fillMethod = ecs::UIFillMethod::Radial360;
            } else {
                auto& sprite = registry.emplace<ecs::Sprite>(entity);
                sprite.size = {20, 30};
                sprite.tileSize = {10, 10};
                sprite.texture = texture;
                const ecs::SpriteDrawMode modes[] = {ecs::SpriteDrawMode::Simple,
                    ecs::SpriteDrawMode::NineSlice, ecs::SpriteDrawMode::Tiled};
                sprite.drawMode = modes[mode];
            }
            Frustum frustum;
            frustum.extractFromMatrix(glm::ortho(-500.0f, 500.0f, -500.0f, 500.0f));
            RenderFrameContext frameContext{context, resources};
            RenderCollectContext collect{registry, frustum, h.clips, h.pool, h.list, frameContext, {}};
            UIElementPlugin uiPlugin;
            SpritePlugin spritePlugin;
            uiPlugin.init(frameContext);
            spritePlugin.init(frameContext);
            for (bool collapsed : {true, false, true}) {
                transform.cachedMatrix_[1] = collapsed ? glm::vec4(.5f, .5f, 0, 0) : glm::vec4(.5f, -.5f, 0, 0);
                transform.decomposed_ = false;
                h.pool.beginFrame();
                h.list.clear();
                if (ui) uiPlugin.collect(collect);
                else spritePlugin.collect(collect);
                CHECK((h.pool.vertexBytesUsed(LayoutId::Batch) == 0) == collapsed);
                CHECK((h.pool.indicesUsed(LayoutId::Batch) == 0) == collapsed);
            }
            resources.shutdown();
        }
    }
}

TEST_CASE("UI masks: collapsed parent bases clip the complete subtree") {
    for (auto mode : {ecs::MaskMode::Scissor, ecs::MaskMode::Stencil}) {
        MockGfxDevice device;
        RenderContext context(device);
        resource::ResourceManager resources;
        ecs::Registry registry;
        RenderFrame frame(device, context, resources);
        frame.init(64, 64);
        const auto parent = registry.create(), mask = registry.create(), child = registry.create();
        registry.emplace<ecs::Parent>(mask).entity = parent;
        registry.emplace<ecs::Children>(mask).entities.push_back(child);
        registry.emplace<ecs::Parent>(child).entity = mask;
        auto& transform = registry.emplace<ecs::Transform>(mask);
        transform.cachedMatrix_[0] = {1, 1, 0, 0};
        registry.emplace<ecs::UINode>(mask).computed_size_ = {20, 20};
        registry.emplace<ecs::UIMask>(mask).mode = mode;
        const f32 vertices[36] = {};
        const u16 indices[] = {0, 1, 2, 2, 3, 0};
        const glm::mat4 identity(1);
        for (bool collapsed : {true, false, true}) {
            transform.cachedMatrix_[1] = collapsed ? glm::vec4(.5f, .5f, 0, 0) : glm::vec4(.5f, -.5f, 0, 0);
            transform.decomposed_ = false;
            frame.beginFrame();
            frame.begin(glm::ortho(-32.0f, 32.0f, -32.0f, 32.0f));
            frame.processMasks(registry, 0, 0, 64, 64);
            frame.collectAll(registry);
            const auto uploads = device.updateBufferCalls;
            frame.submitTextBatch(vertices, 4, indices, 6, 1, &identity[0][0], child, 0, 0, TextGlyphMode::Color);
            frame.flush();
            frame.end();
            CHECK(frame.stats().text == (collapsed ? 0 : 1));
            if (collapsed) CHECK(device.updateBufferCalls == uploads);
            frame.endFrame();
        }
    }
}

TEST_CASE("flat geometry: tiny finite and tilted spans retain their area") {
    ecs::Transform transform;
    transform.cachedMatrix_[0] = {1, 1, 0, 0};
    transform.cachedMatrix_[1] = {.5f, .5f, 0, 0};
    CHECK_FALSE(ecs::hasFlatGeometryArea(transform, true));
    CHECK(ecs::hasFlatGeometryArea(transform, false));
    transform.cachedMatrix_[1].z = 1;
    CHECK(ecs::hasFlatGeometryArea(transform, true));
    transform.cachedMatrix_[0] = {1e-30f, 0, 0, 0};
    transform.cachedMatrix_[1] = {0, 1e-30f, 0, 0};
    CHECK(ecs::hasFlatGeometryArea(transform, true));
    transform.cachedMatrix_[1].y = std::numeric_limits<f32>::infinity();
    CHECK_FALSE(ecs::hasFlatGeometryArea(transform, true));
}

TEST_CASE("flat geometry: authored planar zero scales remain collapsed through rotation") {
    for (f32 angle : {0.0f, .4f, .7f}) {
        ecs::Registry registry;
        ecs::TransformSystem system;
        const auto parent = registry.create(), group = registry.create(), child = registry.create();
        auto& root = registry.emplace<ecs::Transform>(parent);
        root.scale.x = 0;
        root.rotation = glm::angleAxis(.7f, glm::vec3(0, 0, 1));
        auto& transform = registry.emplace<ecs::Transform>(child);
        transform.rotation = glm::angleAxis(angle, glm::vec3(0, 0, 1));
        ecs::setParent(registry, group, parent);
        ecs::setParent(registry, child, group);
        system.ensureComposed(registry);
        CHECK_FALSE(ecs::hasFlatGeometryArea(registry, child, transform));
        CHECK_FALSE(ecs::pointInTransformedBox(registry, child, transform, 0, 0, 20, 30, .5f, .5f));
        registry.get<ecs::Transform>(parent).scale.x = 1;
        ecs::invalidateTransformComposition();
        system.ensureComposed(registry);
        CHECK(ecs::hasFlatGeometryArea(registry, child, transform));
        CHECK(ecs::pointInTransformedBox(registry, child, transform, 0, 0, 20, 30, .5f, .5f));
        registry.get<ecs::Transform>(parent).scale.x = 0;
        transform.rotation = glm::angleAxis(.5f, glm::vec3(0, 1, 0));
        ecs::invalidateTransformComposition();
        system.ensureComposed(registry);
        CHECK(ecs::hasFlatGeometryArea(registry, child, transform));
        ecs::setParent(registry, child, INVALID_ENTITY);
        system.ensureComposed(registry);
        CHECK(ecs::hasFlatGeometryArea(registry, child, transform));
    }
}

TEST_CASE("flat geometry: deep collapsed groups propagate and recover in one traversal") {
    ecs::Registry registry;
    ecs::TransformSystem system;
    const auto root = registry.create();
    registry.emplace<ecs::Transform>(root).scale.x = 0;
    auto parent = root;
    for (u32 i = 0; i < 50000; ++i) {
        const auto child = registry.create();
        registry.emplace<ecs::Parent>(child).entity = parent;
        registry.emplace<ecs::Children>(parent).entities.push_back(child);
        parent = child;
    }
    auto& transform = registry.emplace<ecs::Transform>(parent);
    transform.rotation = glm::angleAxis(.4f, glm::vec3(0, 0, 1));
    system.ensureComposed(registry);
    CHECK_FALSE(ecs::hasFlatGeometryArea(registry, parent, transform));
    registry.get<ecs::Transform>(root).scale.x = 1;
    ecs::invalidateTransformComposition();
    system.ensureComposed(registry);
    CHECK(ecs::hasFlatGeometryArea(registry, parent, transform));
    CHECK(registry.entitiesWith<ecs::FlatGeometryCollapsed>().empty());
}

TEST_CASE("bitmap text: collapsed parent bases skip long glyph runs and recover") {
    Harness h;
    RenderContext context(h.device);
    resource::ResourceManager resources;
    resources.init(h.device);
    const u8 pixels[16 * 16 * 4] = {};
    const auto texture = resources.createTexture(resource::ResourceContent::Retained,
                                                 16, 16, pixels, TextureFormat::RGBA8);
    const auto font = resources.createBitmapFont(
        "common lineHeight=16 base=12 scaleW=16 scaleH=16 pages=1\n"
        "char id=65 x=0 y=0 width=8 height=16 xoffset=0 yoffset=0 xadvance=10 page=0 chnl=15\n",
        texture, 16, 16);
    REQUIRE(font.isValid());
    ecs::Registry registry;
    const auto parent = registry.create(), entity = registry.create();
    registry.emplace<ecs::Parent>(entity).entity = parent;
    auto& transform = registry.emplace<ecs::Transform>(entity);
    transform.cachedMatrix_[0] = {1, 1, 0, 0};
    auto& text = registry.emplace<ecs::BitmapText>(entity);
    text.font = font;
    text.text = std::string(65536, 'A');
    Frustum frustum;
    frustum.extractFromMatrix(glm::ortho(-1e7f, 1e7f, -1e7f, 1e7f));
    RenderFrameContext frameContext{context, resources};
    RenderCollectContext collect{registry, frustum, h.clips, h.pool, h.list, frameContext, {}};
    TextPlugin plugin;
    plugin.init(frameContext);
    for (bool collapsed : {true, false, true}) {
        transform.cachedMatrix_[1] = collapsed ? glm::vec4(.5f, .5f, 0, 0) : glm::vec4(.5f, -.5f, 0, 0);
        transform.decomposed_ = false;
        h.pool.beginFrame();
        h.list.clear();
        plugin.collect(collect);
        CHECK(h.pool.vertexBytesUsed(LayoutId::Batch) == (collapsed ? 0 : 65536 * 4 * sizeof(BatchVertex)));
        CHECK(h.pool.indicesUsed(LayoutId::Batch) == (collapsed ? 0 : 65536 * 6));
    }
    resources.shutdown();
}

TEST_CASE("text transform bridge: full parent basis and childless root TRS reach the caller") {
    ecs::Registry registry;
    const auto parent = registry.create(), child = registry.create();
    registry.emplace<ecs::Parent>(child).entity = parent;
    auto& transform = registry.emplace<ecs::Transform>(child);
    transform.cachedMatrix_ = glm::mat4(1);
    transform.cachedMatrix_[0] = {2, 1, 0, 0};
    transform.cachedMatrix_[1] = {3, 4, 0, 0};
    transform.cachedMatrix_[3] = {13, 17, 0, 1};
    transform.decomposed_ = false;
    glm::mat4 output(9);
    CHECK(ecs::copyFlatRenderMatrix(registry, child, output));
    CHECK(output == transform.cachedMatrix_);
    registry.emplace<ecs::FlatGeometryCollapsed>(child);
    const auto retained = output;
    CHECK_FALSE(ecs::copyFlatRenderMatrix(registry, child, output));
    CHECK(output == retained);
    CHECK_FALSE(ecs::copyFlatRenderMatrix(registry, INVALID_ENTITY, output));
    const auto root = registry.create();
    auto& rootTransform = registry.emplace<ecs::Transform>(root);
    rootTransform.worldPosition = {4, 7, 2};
    rootTransform.worldScale = {-2, 3, 4};
    rootTransform.worldRotation = glm::angleAxis(.7f, glm::vec3(0, 1, 0));
    CHECK(ecs::copyFlatRenderMatrix(registry, root, output));
    CHECK(output == math::compose(rootTransform.worldPosition, rootTransform.worldRotation, rootTransform.worldScale));
    CHECK(std::isnan(rootTransform.cachedMatrix_[0][0]));
}

TEST_CASE("sprites: tile budget applies before integer conversion") {
    struct Case { glm::vec2 tile, spacing; u32 quads; };
    const Case cases[] = {
        {{1e-20f, 1}, {}, 1},
        {{1, 1e-20f}, {}, 1},
        {{std::numeric_limits<f32>::denorm_min(), 1}, {}, 1},
        {{1e-20f, 1e-20f}, {}, 1},
        {{1, 1}, {}, 16384},
        {{.5f, 1}, {}, 1},
        {{1, 1}, {-1, 0}, 0},
        {{1, 1}, {std::numeric_limits<f32>::quiet_NaN(), 0}, 0},
        {{1, 1}, {std::numeric_limits<f32>::infinity(), 0}, 0},
    };
    for (const auto& item : cases) {
        Harness h;
        RenderContext context(h.device);
        resource::ResourceManager resources;
        resources.init(h.device);
        ecs::Registry registry;
        const auto entity = registry.create();
        auto& transform = registry.emplace<ecs::Transform>(entity);
        transform.worldScale = {1, 1, 1};
        transform.decomposed_ = true;
        auto& sprite = registry.emplace<ecs::Sprite>(entity);
        sprite.size = {128, 128};
        sprite.tileSize = item.tile;
        sprite.tileSpacing = item.spacing;
        sprite.drawMode = ecs::SpriteDrawMode::Tiled;
        Frustum frustum;
        frustum.extractFromMatrix(glm::ortho(-500.0f, 500.0f, -500.0f, 500.0f));
        RenderFrameContext frameContext{context, resources};
        RenderCollectContext collect{registry, frustum, h.clips, h.pool, h.list, frameContext, {}};
        SpritePlugin plugin;
        plugin.init(frameContext);
        plugin.collect(collect);
        CHECK(h.pool.vertexBytesUsed(LayoutId::Batch) == item.quads * 4 * sizeof(BatchVertex));
        const auto* vertices = reinterpret_cast<const BatchVertex*>(h.pool.vertexData(LayoutId::Batch));
        bool finite = true;
        for (u32 i = 0; i < h.pool.vertexBytesUsed(LayoutId::Batch) / sizeof(BatchVertex); ++i) {
            finite = finite && std::isfinite(vertices[i].position.x) && std::isfinite(vertices[i].position.y);
        }
        CHECK(finite);
        resources.shutdown();
    }
}

TEST_CASE("bitmap text: world geometry follows affine transforms and parallax") {
    for (u32 kind : {0u, 1u, 2u}) {
        const bool alignedEdge = kind == 1, rootWithoutMatrix = kind == 2;
        Harness h;
        RenderContext context(h.device);
        resource::ResourceManager resources;
        resources.init(h.device);
        const u8 pixels[16 * 16 * 4] = {};
        const auto texture = resources.createTexture(resource::ResourceContent::Retained, 16, 16,
                                                     pixels, TextureFormat::RGBA8);
        REQUIRE(texture.isValid());
        const auto font = resources.createBitmapFont(
            "common lineHeight=16 base=12 scaleW=16 scaleH=16 pages=1\n"
            "char id=65 x=0 y=0 width=8 height=16 xoffset=2 yoffset=1 xadvance=10 page=0 chnl=15\n",
            texture, 16, 16);
        REQUIRE(font.isValid());
        ecs::Registry registry;
        const auto entity = registry.create();
        auto& transform = registry.emplace<ecs::Transform>(entity);
        auto& text = registry.emplace<ecs::BitmapText>(entity);
        text.font = font;
        text.text = "A";
        glm::mat4 projection;
        if (alignedEdge) {
            text.align = ecs::TextAlign::Right;
            transform.cachedMatrix_ = glm::translate(glm::mat4(1), glm::vec3(7, 0, 0));
            projection = glm::ortho(-1.0f, 1.0f, -20.0f, 20.0f);
        } else if (rootWithoutMatrix) {
            transform.worldPosition = {4, -7, 0};
            transform.worldRotation = glm::angleAxis(.7f, glm::vec3(0, 0, 1));
            transform.worldScale = {-2, 3, 1};
            text.parallax = {.5f, .25f};
            projection = glm::ortho(-100.0f, 100.0f, -100.0f, 100.0f);
        } else {
            const auto parent = registry.create();
            registry.emplace<ecs::Parent>(entity).entity = parent;
            registry.emplace<ecs::Children>(parent).entities.push_back(entity);
            transform.cachedMatrix_ = glm::scale(glm::mat4(1), glm::vec3(2, 1, 1))
                                    * glm::translate(glm::mat4(1), glm::vec3(4, -7, 0))
                                    * glm::mat4_cast(glm::angleAxis(.7f, glm::vec3(0, 0, 1)))
                                    * glm::scale(glm::mat4(1), glm::vec3(-2, 3, 1));
            text.parallax = {.5f, .25f};
            projection = glm::ortho(-100.0f, 100.0f, -100.0f, 100.0f);
        }
        transform.decomposed_ = rootWithoutMatrix;
        Frustum frustum;
        frustum.extractFromMatrix(projection);
        RenderFrameContext frameContext{context, resources};
        RenderCollectContext collect{registry, frustum, h.clips, h.pool, h.list, frameContext, {}};
        collect.camera.center = {10, 20};
        TextPlugin plugin;
        plugin.init(frameContext);
        plugin.collect(collect);
        REQUIRE(h.pool.vertexBytesUsed(LayoutId::Batch) == 4 * sizeof(BatchVertex));
        CHECK(h.pool.indicesUsed(LayoutId::Batch) == 6);
        const auto* vertices = reinterpret_cast<const BatchVertex*>(h.pool.vertexData(LayoutId::Batch));
        const glm::vec2 local[] = {{2, -5}, {10, -5}, {10, 11}, {2, 11}};
        for (u32 i = 0; i < 4; ++i) {
            const auto matrix = rootWithoutMatrix
                ? glm::translate(glm::mat4(1), transform.worldPosition) * glm::mat4_cast(transform.worldRotation)
                  * glm::scale(glm::mat4(1), transform.worldScale)
                : transform.cachedMatrix_;
            const glm::vec3 origin = glm::vec3(matrix * glm::vec4(local[i].x - (alignedEdge ? 10 : 0), local[i].y, 0, 1));
            const auto expected = origin + glm::vec3(collect.camera.center * (glm::vec2(1) - text.parallax), 0);
            CHECK(vertices[i].position.x == doctest::Approx(expected.x));
            CHECK(vertices[i].position.y == doctest::Approx(expected.y));
        }
        resources.shutdown();
    }
}

TEST_CASE("bitmap text: UTF-8 strings retain every glyph beyond 64 KiB") {
    for (u32 length : {65535u, 65536u, 65537u, 65539u}) {
        Harness h;
        RenderContext context(h.device);
        resource::ResourceManager resources;
        resources.init(h.device);
        const u8 pixels[16 * 16 * 4] = {};
        const auto texture = resources.createTexture(resource::ResourceContent::Retained, 16, 16,
                                                     pixels, TextureFormat::RGBA8);
        const auto font = resources.createBitmapFont(
            "common lineHeight=16 base=16 scaleW=16 scaleH=16 pages=1\n"
            "char id=65 x=0 y=0 width=8 height=16 xoffset=0 yoffset=0 xadvance=8 page=0 chnl=15\n"
            "char id=128512 x=8 y=0 width=8 height=16 xoffset=0 yoffset=0 xadvance=8 page=0 chnl=15\n",
            texture, 16, 16);
        REQUIRE(font.isValid());
        ecs::Registry registry;
        const auto entity = registry.create();
        registry.emplace<ecs::Transform>(entity);
        auto& text = registry.emplace<ecs::BitmapText>(entity);
        text.font = font;
        text.align = ecs::TextAlign::Right;
        text.text = length == 65539 ? std::string(65534, 'A') + "\xf0\x9f\x98\x80" + "A" : std::string(length, 'A');
        const u32 glyphs = length == 65539 ? 65536 : length;
        Frustum frustum;
        frustum.extractFromMatrix(glm::ortho(-1000000.0f, 1000000.0f, -32.0f, 32.0f));
        RenderFrameContext frameContext{context, resources};
        RenderCollectContext collect{registry, frustum, h.clips, h.pool, h.list, frameContext, {}};
        TextPlugin plugin;
        plugin.init(frameContext);
        plugin.collect(collect);
        CHECK(h.pool.vertexBytesUsed(LayoutId::Batch) == glyphs * 4 * sizeof(BatchVertex));
        CHECK(h.pool.indicesUsed(LayoutId::Batch) == glyphs * 6);
        if (h.pool.vertexBytesUsed(LayoutId::Batch) == glyphs * 4 * sizeof(BatchVertex)) {
            const auto* vertices = reinterpret_cast<const BatchVertex*>(h.pool.vertexData(LayoutId::Batch));
            CHECK(vertices[0].position.x == doctest::Approx(-8.0f * glyphs));
            CHECK(vertices[glyphs * 4 - 2].position.x == doctest::Approx(0));
            CHECK(h.pool.indexData(LayoutId::Batch)[glyphs * 6 - 2] == glyphs * 4 - 1);
        }
        h.pool.beginFrame();
        h.list.clear();
        frustum.extractFromMatrix(glm::ortho(-16.0f, 0.0f, -32.0f, 32.0f));
        plugin.collect(collect);
        CHECK(h.pool.vertexBytesUsed(LayoutId::Batch) == 3 * 4 * sizeof(BatchVertex));
        CHECK(h.pool.indicesUsed(LayoutId::Batch) == 18);
        if (h.pool.vertexBytesUsed(LayoutId::Batch) == 3 * 4 * sizeof(BatchVertex)) {
            const auto* vertices = reinterpret_cast<const BatchVertex*>(h.pool.vertexData(LayoutId::Batch));
            CHECK(vertices[10].position.x == doctest::Approx(0));
            CHECK(h.pool.indexData(LayoutId::Batch)[16] == 11);
        }
        h.pool.beginFrame();
        h.list.clear();
        frustum.extractFromMatrix(glm::ortho(-520.0f, -504.0f, -32.0f, 32.0f));
        plugin.collect(collect);
        CHECK(h.pool.vertexBytesUsed(LayoutId::Batch) == 4 * 4 * sizeof(BatchVertex));
        CHECK(h.pool.indicesUsed(LayoutId::Batch) == 24);
        if (h.pool.vertexBytesUsed(LayoutId::Batch) == 4 * 4 * sizeof(BatchVertex)) {
            const auto* vertices = reinterpret_cast<const BatchVertex*>(h.pool.vertexData(LayoutId::Batch));
            CHECK(vertices[0].position.x == doctest::Approx(-528));
            CHECK(vertices[14].position.x == doctest::Approx(-496));
        }
        resources.shutdown();
    }
}

TEST_CASE("UI masks: deep grouping hierarchies reach their leaf without call-stack recursion") {
    for (auto mode : {ecs::MaskMode::Scissor, ecs::MaskMode::Stencil}) {
        MockGfxDevice device;
        RenderContext context(device);
        resource::ResourceManager resources;
        ecs::Registry registry;
        RenderFrame frame(device, context, resources);
        frame.init(64, 64);
        const auto root = registry.create();
        registry.emplace<ecs::Transform>(root);
        registry.get<ecs::Transform>(root).worldRotation = glm::angleAxis(.7f, glm::vec3(0, 0, 1));
        registry.get<ecs::Transform>(root).worldScale.y = -1;
        auto& node = registry.emplace<ecs::UINode>(root);
        node.computed_size_ = {20, 20};
        registry.emplace<ecs::UIMask>(root).mode = mode;
        Entity leaf = root;
        for (u32 i = 0; i < 50000; ++i) {
            const auto child = registry.create();
            registry.emplace<ecs::Parent>(child).entity = leaf;
            registry.emplace<ecs::Children>(leaf).entities.push_back(child);
            leaf = child;
        }
        const glm::mat4 projection = glm::ortho(-32.0f, 32.0f, -32.0f, 32.0f);
        const glm::mat4 transform(1);
        const f32 text[36] = {};
        const u16 indices[] = {0, 1, 2, 2, 3, 0};
        for (bool empty : {true, false}) {
            node.computed_size_.x = empty ? 0 : 20;
            frame.beginFrame();
            frame.begin(projection);
            frame.processMasks(registry, 0, 0, 64, 64);
            frame.collectAll(registry);
            const int uploads = device.updateBufferCalls;
            frame.submitTextBatch(text, 4, indices, 6, 1, &transform[0][0], leaf, 0, 0, TextGlyphMode::Color);
            frame.flush();
            if (empty) {
                CHECK(frame.stats().text == 0);
                CHECK(device.updateBufferCalls == uploads);
            } else {
                CHECK(frame.stats().text == 1);
                CHECK(device.updateBufferCalls > uploads);
            }
            frame.end();
            frame.endFrame();
        }
    }
}

TEST_CASE("UI stencil traversal keeps nested and sibling references in authored order") {
    MockGfxDevice device;
    RenderContext context(device);
    resource::ResourceManager resources;
    ecs::Registry registry;
    RenderFrame frame(device, context, resources);
    frame.init(64, 64);
    const auto child = [&](Entity parent, bool mask) {
        const Entity entity = registry.create();
        if (parent != INVALID_ENTITY) {
            registry.emplace<ecs::Parent>(entity).entity = parent;
            if (!registry.has<ecs::Children>(parent)) registry.emplace<ecs::Children>(parent);
            registry.get<ecs::Children>(parent).entities.push_back(entity);
        }
        if (mask) registry.emplace<ecs::UIMask>(entity).mode = ecs::MaskMode::Stencil;
        return entity;
    };
    const Entity root = child(INVALID_ENTITY, true), a = child(root, false), nested = child(root, true);
    const Entity b = child(nested, false), deep = child(nested, true), c = child(deep, false);
    const Entity group = child(root, false), d = child(group, false), e = child(root, false);
    registry.emplace<ecs::Transform>(deep).cachedMatrix_ = glm::mat4(1);
    auto& nestedBox = registry.emplace<ecs::UINode>(deep);
    nestedBox.computed_size_ = {20, 20};
    const glm::mat4 transform(1);
    const f32 text[36] = {};
    const u16 indices[] = {0, 1, 2, 2, 3, 0};
    for (u32 repeat = 0; repeat < 4; ++repeat) {
        const bool empty = repeat == 2;
        nestedBox.computed_size_.y = empty ? 0 : 20;
        device.stencilReferences.clear();
        frame.beginFrame();
        frame.begin(transform);
        frame.processMasks(registry, 0, 0, 64, 64);
        frame.collectAll(registry);
        i32 layer = 0;
        for (Entity entity : {root, a, nested, b, deep, c, d, e}) {
            frame.submitTextBatch(text, 4, indices, 6, 1, &transform[0][0], entity, layer++, 0, TextGlyphMode::Color);
        }
        frame.flush();
        frame.end();
        CHECK(frame.stats().text == (empty ? 6 : 8));
        const std::vector<i32> expected = empty
            ? std::vector<i32>{1, 1, 1, 2, 2, 1, 1}
            : std::vector<i32>{1, 1, 1, 2, 2, 3, 3, 2, 1, 1};
        CHECK(device.stencilReferences.size() == expected.size());
        for (u32 i = 0; i < std::min(device.stencilReferences.size(), expected.size()); ++i) {
            CHECK(device.stencilReferences[i] == expected[i]);
        }
        frame.endFrame();
    }
}

TEST_CASE("flat bounds: reflected extents enclose the same rotated box") {
    for (f32 x : {1.0f, -1.0f}) for (f32 y : {1.0f, -1.0f}) {
        for (f32 angle : {0.0f, .7f}) {
            const auto extent = flatHalfExtents({std::cos(angle), std::sin(angle)}, {3*x, 5*y, -2});
            CHECK(extent.x == doctest::Approx(std::abs(std::cos(angle))*3 + std::abs(std::sin(angle))*5));
            CHECK(extent.y == doctest::Approx(std::abs(std::sin(angle))*3 + std::abs(std::cos(angle))*5));
            CHECK(extent.z == 2);
        }
    }
}

TEST_CASE("UI stencil reference budget follows depth rather than sibling count") {
    MockGfxDevice device;
    RenderContext context(device);
    resource::ResourceManager resources;
    ecs::Registry registry;
    RenderFrame frame(device, context, resources);
    frame.init(64, 64);
    const Entity root = registry.create();
    registry.emplace<ecs::UIMask>(root).mode = ecs::MaskMode::Stencil;
    registry.emplace<ecs::Children>(root);
    std::vector<Entity> ordered{root};
    for (u32 i = 0; i < 300; ++i) {
        const Entity mask = registry.create(), content = registry.create();
        registry.emplace<ecs::Parent>(mask).entity = root;
        registry.emplace<ecs::Parent>(content).entity = mask;
        registry.get<ecs::Children>(root).entities.push_back(mask);
        registry.emplace<ecs::Children>(mask).entities.push_back(content);
        registry.emplace<ecs::UIMask>(mask).mode = ecs::MaskMode::Stencil;
        ordered.push_back(mask);
        ordered.push_back(content);
    }
    const glm::mat4 transform(1);
    const f32 text[36] = {};
    const u16 indices[] = {0, 1, 2, 2, 3, 0};
    frame.beginFrame();
    frame.begin(transform);
    frame.processMasks(registry, 0, 0, 64, 64);
    frame.collectAll(registry);
    i32 layer = 0;
    for (Entity entity : ordered) {
        frame.submitTextBatch(text, 4, indices, 6, 1, &transform[0][0], entity, layer++, 0, TextGlyphMode::Color);
    }
    frame.flush();
    frame.end();
    CHECK(frame.stats().text == 601);
    REQUIRE(device.stencilReferences.size() == 902);
    for (u32 i = 0; i < 300; ++i) {
        CHECK(device.stencilReferences[1 + i * 3] == 1);
        CHECK(device.stencilReferences[2 + i * 3] == 2);
        CHECK(device.stencilReferences[3 + i * 3] == 2);
    }
    frame.endFrame();
}

TEST_CASE("detached UI refreshes inherited state without relocating its geometry") {
    ecs::Registry registry;
    ecs::UISystem ui;
    const auto child = [&](Entity parent, bool node) {
        const Entity entity = registry.create();
        registry.emplace<ecs::Transform>(entity);
        if (node) registry.emplace<ecs::UINode>(entity);
        if (parent != INVALID_ENTITY) {
            registry.emplace<ecs::Parent>(entity).entity = parent;
            if (!registry.has<ecs::Children>(parent)) registry.emplace<ecs::Children>(parent);
            registry.get<ecs::Children>(parent).entities.push_back(entity);
        }
        return entity;
    };
    const Entity root = child(INVALID_ENTITY, true);
    registry.emplace<ecs::Canvas>(root);
    const Entity group = child(root, false), leaf = child(group, true);
    registry.get<ecs::UINode>(root).opacity = .5f;
    registry.get<ecs::UINode>(leaf).opacity = .5f;
    ui.layoutUpdate(registry, -100, -100, 100, 100, true);
    CHECK(registry.get<ecs::UINode>(leaf).alpha_in_tree_ == doctest::Approx(.25f));
    const auto position = registry.get<ecs::Transform>(leaf).position;
    const auto size = registry.get<ecs::UINode>(leaf).computed_size_;
    registry.remove<ecs::Canvas>(root);
    auto& parent = registry.get<ecs::UINode>(root);
    parent.display = ecs::UIDisplay::None;
    parent.pointerEvents = ecs::UIPointerEvents::None;
    ui.layoutUpdate(registry, -200, -200, 200, 200, true);
    CHECK(ui.tree.nodes_.empty());
    CHECK(parent.hidden_in_tree_);
    CHECK(registry.get<ecs::UINode>(leaf).hidden_in_tree_);
    CHECK(registry.get<ecs::UINode>(leaf).pointer_blocked_in_tree_);
    CHECK(registry.get<ecs::Transform>(leaf).position == position);
    CHECK(registry.get<ecs::UINode>(leaf).computed_size_ == size);
    parent.display = ecs::UIDisplay::Flex;
    parent.pointerEvents = ecs::UIPointerEvents::Auto;
    parent.opacity = .8f;
    ui.layoutUpdate(registry, -200, -200, 200, 200, false);
    CHECK_FALSE(registry.get<ecs::UINode>(leaf).hidden_in_tree_);
    CHECK_FALSE(registry.get<ecs::UINode>(leaf).pointer_blocked_in_tree_);
    CHECK(registry.get<ecs::UINode>(leaf).alpha_in_tree_ == doctest::Approx(.4f));
    registry.emplace<ecs::Canvas>(root);
    ui.layoutUpdate(registry, -100, -100, 100, 100, false);
    CHECK(ui.tree.nodes_.size() == 2);
    CHECK(registry.get<ecs::UINode>(leaf).alpha_in_tree_ == doctest::Approx(.4f));
}

TEST_CASE("pointer events: Receive takes the pointer back under a None ancestor, in and out of the layout tree") {
    for (bool inTree : {true, false}) {
        ecs::Registry registry;
        ecs::UISystem ui;
        const auto node = [&](Entity parent, ecs::UIPointerEvents pe) {
            const Entity e = registry.create();
            registry.emplace<ecs::Transform>(e);
            registry.emplace<ecs::UINode>(e).pointerEvents = pe;
            if (parent != INVALID_ENTITY) {
                registry.emplace<ecs::Parent>(e).entity = parent;
                if (!registry.has<ecs::Children>(parent)) registry.emplace<ecs::Children>(parent);
                registry.get<ecs::Children>(parent).entities.push_back(e);
            }
            return e;
        };
        const Entity overlay = node(INVALID_ENTITY, ecs::UIPointerEvents::None);
        if (inTree) registry.emplace<ecs::Canvas>(overlay);
        const Entity label = node(overlay, ecs::UIPointerEvents::Auto);
        const Entity close = node(overlay, ecs::UIPointerEvents::Receive);
        const Entity icon = node(close, ecs::UIPointerEvents::Auto);
        const Entity quiet = node(close, ecs::UIPointerEvents::None);
        ui.layoutUpdate(registry, -100, -100, 100, 100, true);
        const auto blocked = [&](Entity e) { return registry.get<ecs::UINode>(e).pointer_blocked_in_tree_; };
        CAPTURE(inTree);
        CHECK(blocked(overlay));
        CHECK(blocked(label));
        CHECK_FALSE(blocked(close));
        CHECK_FALSE(blocked(icon));
        CHECK(blocked(quiet));
    }
}

TEST_CASE("detached UI state walks shared deep ancestry iteratively and recovers from reparenting") {
    ecs::Registry registry;
    ecs::UISystem ui;
    const Entity root = registry.create();
    auto& parent = registry.emplace<ecs::UINode>(root);
    parent.display = ecs::UIDisplay::None;
    parent.opacity = .5f;
    parent.pointerEvents = ecs::UIPointerEvents::None;
    Entity group = root;
    for (u32 i = 0; i < 50000; ++i) {
        const Entity next = registry.create();
        registry.emplace<ecs::Parent>(next).entity = group;
        group = next;
    }
    std::vector<Entity> leaves;
    for (u32 i = 0; i < 100; ++i) {
        const Entity leaf = registry.create();
        registry.emplace<ecs::Parent>(leaf).entity = group;
        registry.emplace<ecs::UINode>(leaf).opacity = .25f;
        leaves.push_back(leaf);
    }
    ui.layoutUpdate(registry, -100, -100, 100, 100, false);
    for (Entity leaf : leaves) {
        const auto& node = registry.get<ecs::UINode>(leaf);
        CHECK(node.hidden_in_tree_);
        CHECK(node.pointer_blocked_in_tree_);
        CHECK(node.alpha_in_tree_ == doctest::Approx(.125f));
    }
    const Entity visible = registry.create();
    registry.emplace<ecs::UINode>(visible).opacity = .8f;
    registry.get<ecs::Parent>(group).entity = visible;
    ui.layoutUpdate(registry, -100, -100, 100, 100, false);
    for (Entity leaf : leaves) {
        const auto& node = registry.get<ecs::UINode>(leaf);
        CHECK_FALSE(node.hidden_in_tree_);
        CHECK_FALSE(node.pointer_blocked_in_tree_);
        CHECK(node.alpha_in_tree_ == doctest::Approx(.2f));
    }
}

TEST_CASE("a Canvas inherits visibility and pointer policy from an ancestor outside its layout tree") {
    ecs::Registry registry;
    ecs::UISystem ui;
    ecs::TransformSystem transforms;
    const Entity parent = registry.create(), canvas = registry.create(), leaf = registry.create();
    registry.emplace<ecs::Transform>(parent).position = {13, 17, 0};
    registry.emplace<ecs::UINode>(parent).opacity = .5f;
    registry.get<ecs::UINode>(parent).pointerEvents = ecs::UIPointerEvents::None;
    registry.emplace<ecs::Children>(parent).entities.push_back(canvas);
    registry.emplace<ecs::Parent>(canvas).entity = parent;
    registry.emplace<ecs::Transform>(canvas);
    registry.emplace<ecs::UINode>(canvas);
    registry.emplace<ecs::Canvas>(canvas);
    registry.emplace<ecs::Children>(canvas).entities.push_back(leaf);
    registry.emplace<ecs::Parent>(leaf).entity = canvas;
    registry.emplace<ecs::Transform>(leaf);
    auto& node = registry.emplace<ecs::UINode>(leaf);
    node.width = {40, 0};
    node.height = {30, 0};
    node.opacity = .5f;
    registry.emplace<ecs::Interactable>(leaf);
    ui.layoutUpdate(registry, -100, -100, 100, 100, true);
    transforms.ensureComposed(registry);
    REQUIRE(ui.tree.nodes_.size() == 2);
    CHECK(node.alpha_in_tree_ == doctest::Approx(.25f));
    auto& transform = registry.get<ecs::Transform>(leaf);
    transform.ensureDecomposed();
    const auto position = transform.worldPosition;
    const ecs::PickRay ray{{position.x, position.y, 100}, {0, 0, -1}};
    ui.hitTestUpdate(registry, ray, nullptr);
    CHECK(ui.hitResult.hit_entity == INVALID_ENTITY);
    registry.get<ecs::UINode>(parent).pointerEvents = ecs::UIPointerEvents::Auto;
    ui.layoutUpdate(registry, -100, -100, 100, 100, false);
    ui.hitTestUpdate(registry, ray, nullptr);
    CHECK(ui.hitResult.hit_entity == leaf);
    registry.get<ecs::UINode>(parent).display = ecs::UIDisplay::None;
    ui.layoutUpdate(registry, -100, -100, 100, 100, false);
    ui.hitTestUpdate(registry, ray, nullptr);
    CHECK(ui.hitResult.hit_entity == INVALID_ENTITY);
}

TEST_CASE("nine-slice: small boxes contain their borders and preserve source UVs") {
    for (const glm::vec2 size : {glm::vec2{40, 30}, {10, 6}, {10, 30}, {40, 6}, {0, 6}, {10, 0}}) {
        Harness h;
        NineSlicePlugin plugin;
        const glm::vec3 position{13, 17, 0};
        const glm::vec2 pivot{.25f, .75f};
        plugin.emitNineSlice(h.pool, h.list, h.clips, position, size, pivot,
                            0, {100, 100}, {8, 12, 10, 6}, {0, 0}, {1, 1}, {1, 1, 1, 1}, quadKey(1));
        const u32 bytes = h.pool.vertexBytesUsed(LayoutId::Batch);
        if (size.x == 0 || size.y == 0) {
            CHECK(bytes == 0);
            CHECK(h.pool.indicesUsed(LayoutId::Batch) == 0);
            CHECK(h.list.commandCount() == 0);
            continue;
        }
        const auto* vertices = reinterpret_cast<const BatchVertex*>(h.pool.vertexData(LayoutId::Batch));
        const u32 count = bytes / sizeof(BatchVertex);
        REQUIRE(count > 0);
        const glm::vec2 low = glm::vec2(position) - size * pivot;
        const glm::vec2 high = low + size;
        f32 area = 0;
        bool hasLeftUV = false, hasRightUV = false, hasBottomUV = false, hasTopUV = false;
        for (u32 i = 0; i < count; ++i) {
            CHECK(vertices[i].position.x >= low.x - .0001f);
            CHECK(vertices[i].position.x <= high.x + .0001f);
            CHECK(vertices[i].position.y >= low.y - .0001f);
            CHECK(vertices[i].position.y <= high.y + .0001f);
            hasLeftUV |= std::abs(vertices[i].texCoord.x - .08f) < .0001f;
            hasRightUV |= std::abs(vertices[i].texCoord.x - .88f) < .0001f;
            hasBottomUV |= std::abs(vertices[i].texCoord.y - .06f) < .0001f;
            hasTopUV |= std::abs(vertices[i].texCoord.y - .90f) < .0001f;
            if (i % 4 == 0) area += (vertices[i + 1].position.x - vertices[i].position.x)
                                  * (vertices[i + 3].position.y - vertices[i].position.y);
        }
        CHECK(area == doctest::Approx(size.x * size.y));
        CHECK(hasLeftUV);
        CHECK(hasRightUV);
        CHECK(hasBottomUV);
        CHECK(hasTopUV);
    }
}

TEST_CASE("nine-slice: signed transforms and UV flips preserve every cell") {
    NineSlicePlugin plugin;
    const glm::vec3 position{13, 17, 0};
    const glm::vec2 pivot{.25f, .75f}, uvOffset{.2f, .1f}, uvScale{.6f, .8f};
    for (const glm::vec2 size : {glm::vec2{40, 30}, {10, 6}}) {
        Harness reference;
        plugin.emitNineSlice(reference.pool, reference.list, reference.clips, position, size, pivot,
                            0, {100, 100}, {8, 12, 10, 6}, uvOffset, uvScale, {1, 1, 1, 1}, quadKey(1));
        const u32 bytes = reference.pool.vertexBytesUsed(LayoutId::Batch);
        const auto* original = reinterpret_cast<const BatchVertex*>(reference.pool.vertexData(LayoutId::Batch));
        for (f32 signX : {1.0f, -1.0f}) for (f32 signY : {1.0f, -1.0f}) {
            for (f32 flipX : {1.0f, -1.0f}) for (f32 flipY : {1.0f, -1.0f}) {
                for (f32 angle : {0.0f, .4f}) {
                    Harness h;
                    const glm::vec2 offset = uvOffset + glm::vec2(flipX < 0 ? uvScale.x : 0, flipY < 0 ? uvScale.y : 0);
                    plugin.emitNineSlice(h.pool, h.list, h.clips, position, size * glm::vec2(signX, signY), pivot,
                                        angle, {100, 100}, {8, 12, 10, 6}, offset, uvScale * glm::vec2(flipX, flipY),
                                        {1, 1, 1, 1}, quadKey(1));
                    REQUIRE(h.pool.vertexBytesUsed(LayoutId::Batch) == bytes);
                    CHECK(h.pool.indicesUsed(LayoutId::Batch) == reference.pool.indicesUsed(LayoutId::Batch));
                    const auto* vertices = reinterpret_cast<const BatchVertex*>(h.pool.vertexData(LayoutId::Batch));
                    for (u32 i = 0; i < bytes / sizeof(BatchVertex); ++i) {
                        glm::vec2 local = glm::vec2(original[i].position) - glm::vec2(position);
                        if (flipX < 0) local.x = size.x * (1 - 2 * pivot.x) - local.x;
                        if (flipY < 0) local.y = size.y * (1 - 2 * pivot.y) - local.y;
                        local *= glm::vec2(signX, signY);
                        const glm::vec2 expected{position.x + local.x * std::cos(angle) - local.y * std::sin(angle),
                                                 position.y + local.x * std::sin(angle) + local.y * std::cos(angle)};
                        bool found = false;
                        for (u32 j = 0; j < bytes / sizeof(BatchVertex); ++j) {
                            found |= glm::length(glm::vec2(vertices[j].position) - expected) < .0001f
                                  && glm::length(vertices[j].texCoord - original[i].texCoord) < .0001f;
                        }
                        CHECK(found);
                    }
                }
            }
        }
    }
}

TEST_CASE("UI visuals: invisible and collapsed boxes skip geometry and recover") {
    enum class Hidden { OwnAlpha, InheritedAlpha, Width, Height, ScaleX, ScaleY };
    for (auto mode : {ecs::UIVisualType::SolidColor, ecs::UIVisualType::Image,
                      ecs::UIVisualType::NineSlice, ecs::UIVisualType::Tiled,
                      ecs::UIVisualType::Filled}) {
        for (auto hidden : {Hidden::OwnAlpha, Hidden::InheritedAlpha, Hidden::Width,
                            Hidden::Height, Hidden::ScaleX, Hidden::ScaleY}) {
            Harness h;
            RenderContext context(h.device);
            resource::ResourceManager resources;
            ecs::Registry registry;
            const auto entity = registry.create();
            registry.emplace<ecs::Transform>(entity);
            auto& node = registry.emplace<ecs::UINode>(entity);
            node.computed_size_ = {20, 20};
            auto& visual = registry.emplace<ecs::UIVisual>(entity);
            visual.visualType = mode;
            visual.sliceBorder = {2, 2, 2, 2};
            visual.fillMethod = ecs::UIFillMethod::Radial360;
            visual.fillAmount = .5f;
            auto& scale = registry.get<ecs::Transform>(entity).worldScale;
            switch (hidden) {
                case Hidden::OwnAlpha: visual.color.a = 0; break;
                case Hidden::InheritedAlpha: node.alpha_in_tree_ = 0; break;
                case Hidden::Width: node.computed_size_.x = 0; break;
                case Hidden::Height: node.computed_size_.y = 0; break;
                case Hidden::ScaleX: scale.x = 0; break;
                case Hidden::ScaleY: scale.y = 0; break;
            }
            RenderFrameContext frameContext{context, resources};
            frameContext.purpose = RenderPurpose::ScreenOverlay;
            std::unordered_set<u32> screen{entity.id()};
            Frustum frustum;
            RenderCollectContext collect{registry, frustum, h.clips, h.pool, h.list, frameContext, {}};
            collect.screen_ui = &screen;
            UIElementPlugin plugin;
            plugin.init(frameContext);
            plugin.collect(collect);
            CHECK(h.list.commandCount() == 0);
            CHECK(h.pool.vertexBytesUsed(LayoutId::Batch) == 0);
            CHECK(h.pool.indicesUsed(LayoutId::Batch) == 0);
            node.alpha_in_tree_ = .5f;
            visual.color.a = 1;
            node.computed_size_ = {20, 20};
            scale = {1, 1, 1};
            plugin.collect(collect);
            CHECK(h.list.commandCount() > 0);
            CHECK(h.pool.vertexBytesUsed(LayoutId::Batch) > 0);
            CHECK(h.pool.indicesUsed(LayoutId::Batch) > 0);
        }
    }
}

TEST_CASE("UI visuals: transparent stencil masks and custom materials retain geometry") {
    for (int kind : {0, 1, 2}) {
        Harness h;
        RenderContext context(h.device);
        resource::ResourceManager resources;
        ecs::Registry registry;
        const auto entity = registry.create();
        registry.emplace<ecs::Transform>(entity);
        auto& node = registry.emplace<ecs::UINode>(entity);
        node.computed_size_ = {20, 20};
        node.alpha_in_tree_ = 0;
        auto& visual = registry.emplace<ecs::UIVisual>(entity);
        visual.visualType = ecs::UIVisualType::SolidColor;
        if (kind == 0) visual.material = 42;
        if (kind == 1) registry.emplace<ecs::UIMask>(entity).mode = ecs::MaskMode::Stencil;
        if (kind == 2) h.clips.setStencilMask(entity.id(), 1);
        RenderFrameContext frameContext{context, resources};
        frameContext.purpose = RenderPurpose::ScreenOverlay;
        std::unordered_set<u32> screen{entity.id()};
        Frustum frustum;
        RenderCollectContext collect{registry, frustum, h.clips, h.pool, h.list, frameContext, {}};
        collect.screen_ui = &screen;
        UIElementPlugin plugin;
        plugin.init(frameContext);
        plugin.collect(collect);
        CHECK(h.list.commandCount() == 1);
        CHECK(h.pool.vertexBytesUsed(LayoutId::Batch) == 4 * sizeof(BatchVertex));
        CHECK(h.pool.indicesUsed(LayoutId::Batch) == 6);
    }
}

TEST_CASE("camera passes: empty text and skeletal clips recover on the next camera") {
    MockGfxDevice device;
    RenderContext context(device);
    resource::ResourceManager resources;
    ecs::Registry registry;
    RenderFrame frame(device, context, resources);
    frame.init(64, 64);
    const glm::mat4 transform(1.0f);
    const f32 text[36] = {};
    const f32 skeletal[32] = {};
    const u16 indices[] = {0, 1, 2, 2, 3, 0};
    for (const auto& size : {std::pair{0, 10}, std::pair{10, 0}, std::pair{-1, 10}, std::pair{10, -1}}) {
        frame.beginFrame();
        frame.begin(transform);
        frame.setEntityClipRect(1, 0, 0, size.first, size.second);
        frame.setEntityClipRect(2, 0, 0, size.first, size.second);
        frame.collectAll(registry);
        const int uploads = device.updateBufferCalls;
        frame.submitTextBatch(text, 4, indices, 6, 1, &transform[0][0], Entity(1), 0, 0, TextGlyphMode::Color);
        frame.submitSkeletalBatch(skeletal, 4, indices, 6, 1, 0, &transform[0][0], Entity(2), 0, 0, 0, false);
        frame.flush();
        CHECK(device.updateBufferCalls == uploads);
        CHECK(frame.stats().draw_calls == 0);
        frame.end();

        frame.begin(transform);
        frame.clearAllClipRects();
        frame.collectAll(registry);
        frame.submitTextBatch(text, 4, indices, 6, 1, &transform[0][0], Entity(1), 0, 0, TextGlyphMode::Color);
        frame.submitSkeletalBatch(skeletal, 4, indices, 6, 1, 0, &transform[0][0], Entity(2), 0, 0, 0, false);
        frame.flush();
        CHECK(frame.stats().text == 1);
        CHECK(frame.stats().skeletal == 1);
        CHECK(frame.stats().triangles == 4);
        frame.end();
        frame.endFrame();
    }
}

TEST_CASE("camera mask: excluded bulk geometry does not enter transient streams") {
    for (LayoutId layout : {LayoutId::Batch, LayoutId::Shape}) {
        Harness h;
        h.list.setCullingMask(1u << 6);
        auto hidden = quadKey(1, 4);
        hidden.layoutId = layout;
        BatchVertex quad[4] = {};
        TestShapeVertex shape[4] = {};
        const void* verts = layout == LayoutId::Batch ? static_cast<const void*>(quad)
                                                     : static_cast<const void*>(shape);
        for (u32 i = 0; i < 10000; ++i) {
            appendIndexedDraw(h.pool, h.list, h.clips, verts, 4, BATCH_QUAD_INDICES, 6, hidden);
        }
        CHECK(h.list.commandCount() == 0);
        CHECK(h.pool.vertexBytesUsed(layout) == 0);
        CHECK(h.pool.indicesUsed(layout) == 0);

        h.list.setSortingGroup(31, {6, 0, false, 0});
        hidden.entity = Entity(31);
        appendIndexedDraw(h.pool, h.list, h.clips, verts, 4, BATCH_QUAD_INDICES, 6, hidden);
        CHECK(h.list.commandCount() == 1);
        CHECK(h.pool.vertexBytesUsed(layout) == 4 * h.pool.vertexStride(layout));
        CHECK(h.pool.indicesUsed(layout) == 6);
    }
}

TEST_CASE("camera mask: resident geometry skips excluded indices with both source widths") {
    Harness h;
    h.list.setCullingMask(1u << 6);
    BatchVertex quad[4] = {};
    const u32 offset = h.pool.appendVertices(LayoutId::Batch, quad, sizeof(quad));
    const u16 indices16[] = {0, 1, 2, 2, 3, 0};
    auto hidden = quadKey(1, 4);
    pushBatchCommand(h.pool, h.list, h.clips, offset, 4, BATCH_QUAD_INDICES, 6, hidden);
    pushBatchCommand(h.pool, h.list, h.clips, offset, 4, indices16, 6, hidden);
    CHECK(h.pool.indicesUsed(LayoutId::Batch) == 0);
    CHECK(h.pool.vertexBytesUsed(LayoutId::Batch) == sizeof(quad));
    CHECK(h.list.commandCount() == 0);
    hidden.cullBit = 1u << 6;
    pushBatchCommand(h.pool, h.list, h.clips, offset, 4, indices16, 6, hidden);
    CHECK(h.pool.indicesUsed(LayoutId::Batch) == 6);
    CHECK(h.list.commandCount() == 1);
    auto excludedGroup = quadKey(1, 6);
    excludedGroup.entity = Entity(32);
    h.list.setSortingGroup(32, {4, 0, false, 0});
    appendQuad(h.pool, h.list, h.clips, quad, excludedGroup);
    auto excludedBit = quadKey(1, 6);
    excludedBit.cullBit = 1u << 4;
    appendQuad(h.pool, h.list, h.clips, quad, excludedBit);
    CHECK(h.pool.vertexBytesUsed(LayoutId::Batch) == sizeof(quad));
    CHECK(h.pool.indicesUsed(LayoutId::Batch) == 6);
    CHECK(h.list.commandCount() == 1);
    appendQuad(h.pool, h.list, h.clips, quad, quadKey(1, -1));
    CHECK(h.pool.indicesUsed(LayoutId::Batch) == 12);
    CHECK(h.list.commandCount() == 2);
}

TEST_CASE("finalize: full texture slots reject index copies but allow existing textures") {
    for (bool masked : {false, true}) {
        for (bool reuse : {false, true}) {
            Harness h;
            if (masked) {
                h.list.reserveMask2DSlots(1);
                h.list.setMask2DTexture(7, 123);
            }
            const u32 budget = MAX_CMD_TEXTURE_SLOTS - (masked ? 1 : 0);
            BatchVertex quad[4] = {};
            appendQuad(h.pool, h.list, h.clips, quad, quadKey(reuse ? 1 : 99, 2));
            for (u32 texture = 1; texture <= budget; ++texture) {
                appendQuad(h.pool, h.list, h.clips, quad, quadKey(texture, 1));
            }
            const u32 emitted = h.pool.indicesUsed(LayoutId::Batch);
            h.list.finalize(h.pool);
            CHECK(h.list.mergedDrawCallCount() == (reuse ? 1 : 2));
            CHECK(h.pool.indicesUsed(LayoutId::Batch) == emitted + (reuse ? 6 : 0));
            CHECK(h.list.command(0).texture_count == budget);
            CHECK(h.list.command(0).index_count == (budget + (reuse ? 1 : 0)) * 6);
            if (!reuse) {
                CHECK(h.list.command(1).index_offset == 0);
                CHECK(h.list.command(1).break_reason == BatchBreak::TextureSlots);
            }
        }
    }
}

TEST_CASE("index range copies survive staging growth and reject unwritten sources") {
    MockGfxDevice device;
    TransientBufferPool pool{device};
    pool.init(64, 2);
    const u32 values[] = {9,8,7,6,5,4};
    pool.appendIndices(LayoutId::Batch, values, 6);
    u32 at = 99;
    REQUIRE(pool.copyIndexRange(LayoutId::Batch, 0, 6, at));
    CHECK(at == 6);
    for (u32 i = 0; i < 6; i++) CHECK(pool.indexData(LayoutId::Batch)[at + i] == values[i]);
    CHECK_FALSE(pool.copyIndexRange(LayoutId::Batch, 12, 1, at));
    CHECK_FALSE(pool.copyIndexRange(LayoutId::Batch, 0, 13, at));
    CHECK(pool.indicesUsed(LayoutId::Batch) == 12);
    pool.shutdown();
}

TEST_CASE("finalize: mixed Sprite and Text runs preserve source type counts") {
    Harness h;
    BatchVertex quad[4] = {};
    auto sprite = quadKey(10, 2), text = quadKey(11, 1);
    text.type = RenderType::Text;
    appendQuad(h.pool, h.list, h.clips, quad, sprite);
    appendQuad(h.pool, h.list, h.clips, quad, text);
    h.list.finalize(h.pool);
    REQUIRE(h.list.mergedDrawCallCount() == 1);
    CHECK(h.list.sourceEntityCount(RenderType::Sprite) == 1);
    CHECK(h.list.sourceEntityCount(RenderType::Text) == 1);
    h.list.clear();
    CHECK(h.list.sourceEntityCount(RenderType::Sprite) == 0);
    CHECK(h.list.sourceEntityCount(RenderType::Text) == 0);
}

TEST_CASE("finalize: external Batch buffers retain their separate index ranges") {
    Harness h;
    BatchVertex quad[4] = {};
    appendQuad(h.pool, h.list, h.clips, quad, quadKey(10, 2));
    appendQuad(h.pool, h.list, h.clips, quad, quadKey(10, 1));
    auto a = h.list.command(0), b = h.list.command(1);
    a.vertex_buffer = b.vertex_buffer = static_cast<BufferHandle>(123);
    h.list.clear(); h.list.push(a); h.list.push(b);
    h.list.finalize(h.pool);
    CHECK(h.list.mergedDrawCallCount() == 2);
    CHECK(h.pool.indicesUsed(LayoutId::Batch) == 12);
}

TEST_CASE("merge identity: depth bias and geometry bindings must agree") {
    DrawCommand a{}, b{};
    a.shader_id = b.shader_id = 7;
    a.index_count = b.index_count = 6;
    b.index_offset = 6;
    CHECK(a.canMergeWith(b));
    SUBCASE("depth bias") {
        b.depth_bias = 1;
        CHECK_FALSE(a.canMergeWith(b));
    }
    SUBCASE("vertex buffer") {
        a.vertex_buffer = static_cast<BufferHandle>(11);
        b.vertex_buffer = static_cast<BufferHandle>(12);
        CHECK_FALSE(a.canMergeWith(b));
    }
    SUBCASE("index buffer") {
        a.index_buffer = static_cast<BufferHandle>(11);
        b.index_buffer = static_cast<BufferHandle>(12);
        CHECK_FALSE(a.canMergeWith(b));
    }
    SUBCASE("vertex layout") {
        a.vertex_layout = static_cast<VertexLayoutHandle>(11);
        b.vertex_layout = static_cast<VertexLayoutHandle>(12);
        CHECK_FALSE(a.canMergeWith(b));
    }
}

TEST_CASE("finalize: different streams never coalesce; instanced draws stay one per emitter") {
    Harness h;
    BatchVertex quad[4] = {};
    appendQuad(h.pool, h.list, h.clips, quad, quadKey(42));

    TestShapeVertex sverts[4] = {};
    BatchDrawKey shapeKey = quadKey(0);
    shapeKey.layoutId = LayoutId::Shape;
    appendIndexedDraw(h.pool, h.list, h.clips, sverts, 4, BATCH_QUAD_INDICES, 6, shapeKey);

    BatchDrawKey inst = quadKey(42);
    inst.layoutId = LayoutId::ParticleInstance;
    inst.instanceCount = 2;
    pushBatchDraw(h.list, h.clips, 0, 0, 0, 6, inst);
    pushBatchDraw(h.list, h.clips, 80, 0, 0, 6, inst);

    h.list.finalize(h.pool);
    // Batch quad + shape + two instanced draws: nothing merges across these.
    CHECK(h.list.mergedDrawCallCount() == 4);
}

/**
 * A resident-mesh draw as MeshPlugin submits one: the mesh's own buffers, one
 * per-object record in the frame's stream, opaque so its order does not matter.
 * `z` goes into the record so a test can see WHICH instances a merged draw holds.
 */
BatchDrawKey meshKey(u32 meshBuffer, u32 textureId = 0) {
    BatchDrawKey key{};
    key.stage = RenderStage::Opaque;
    key.shaderId = 11;
    key.blend = BlendMode::None;
    key.depthTest = true;
    key.depthWrite = true;
    key.textureId = textureId;
    key.type = RenderType::Mesh;
    key.layoutId = LayoutId::MeshInstance;
    key.instanceCount = 1;
    key.instanceStride = 68;
    key.vertexBuffer = BufferHandle{meshBuffer};
    key.indexBuffer = BufferHandle{meshBuffer + 100};
    // ONE layout for every mesh with these channels, which is what the resource
    // layer hands out: two meshes differ by their buffers, not by their shape.
    // A fixture giving each its own would let a missing buffer check pass.
    key.vertexLayout = VertexLayoutHandle{200};
    return key;
}

/** Submits one instance of `key`'s mesh, tagging its record with `mark`. */
u32 pushMeshInstance(Harness& h, const BatchDrawKey& key, f32 mark, f32 depth = 0.0f) {
    const u32 at = h.pool.allocVertices(LayoutId::MeshInstance, key.instanceStride);
    auto* rec = reinterpret_cast<f32*>(h.pool.vertexData(LayoutId::MeshInstance) + at);
    *rec = mark;
    BatchDrawKey k = key;
    k.depth = depth;
    pushBatchDraw(h.list, h.clips, at, 0, 0, 36, k);
    return at;
}

/** The mark each instance of a merged draw carries, read back from the stream. */
std::vector<f32> instanceMarks(Harness& h, const DrawCommand& cmd) {
    std::vector<f32> out;
    const u8* base = h.pool.vertexData(LayoutId::MeshInstance) + cmd.vertex_byte_offset;
    for (u32 i = 0; i < cmd.instance_count; ++i) {
        out.push_back(*reinterpret_cast<const f32*>(base + i * cmd.instance_stride));
    }
    return out;
}

TEST_CASE("finalize: the same mesh drawn three times is one instanced draw") {
    Harness h;
    BatchDrawKey key = meshKey(5);
    // Written 1,2,3, drawn nearest first (z=1000,10,1): marks 2,3,1, no two records adjacent
    // in the pool, which is why relocation is needed. A mesh's run keeps only the top of the
    // depth's exponent, so these sit in three different steps of it (below 2, to 512, above).
    pushMeshInstance(h, key, 1.0f, 1.0f);
    pushMeshInstance(h, key, 2.0f, 1000.0f);
    pushMeshInstance(h, key, 3.0f, 10.0f);

    h.list.finalize(h.pool);

    REQUIRE(h.list.mergedDrawCallCount() == 1);
    const DrawCommand& cmd = h.list.command(0);
    CHECK(cmd.instance_count == 3);
    CHECK(cmd.index_count == 36);  // one mesh's indices, not three meshes' worth
    CHECK(cmd.entity_count == 3);
    // Every instance is present, in the order the draw will read them.
    CHECK(instanceMarks(h, cmd) == std::vector<f32>{2.0f, 3.0f, 1.0f});
}

/** Submits `count` instances of `key`'s mesh as ONE draw (a set of placements), the n-th record marked `mark + n`. */
void pushMeshInstances(Harness& h, BatchDrawKey key, u32 count, f32 mark, f32 depth) {
    const u32 at = h.pool.allocVertices(LayoutId::MeshInstance, key.instanceStride * count);
    for (u32 n = 0; n < count; ++n) {
        *reinterpret_cast<f32*>(h.pool.vertexData(LayoutId::MeshInstance) + at + n * key.instanceStride) = mark + static_cast<f32>(n);
    }
    key.instanceCount = count;
    key.depth = depth;
    pushBatchDraw(h.list, h.clips, at, 0, 0, 36, key);
}

TEST_CASE("finalize: draws that each place the mesh many times merge with every record carried") {
    Harness h;
    const BatchDrawKey key = meshKey(5);
    // Three draws of 3, 2 and 4 instances; depths reorder them so no two runs are adjacent in the pool
    // (in three different steps of the key's coarse depth, as above).
    pushMeshInstances(h, key, 3, 10.0f, 1.0f);
    pushMeshInstances(h, key, 2, 20.0f, 1000.0f);
    pushMeshInstances(h, key, 4, 30.0f, 10.0f);

    h.list.finalize(h.pool);

    REQUIRE(h.list.mergedDrawCallCount() == 1);
    const DrawCommand& cmd = h.list.command(0);
    CHECK(cmd.instance_count == 9);
    // Nearest first: the draw at depth 1000 (marks 20, 21), then 10 (30..33), then 1 (10..12), each whole.
    CHECK(instanceMarks(h, cmd) == std::vector<f32>{20.0f, 21.0f, 30.0f, 31.0f, 32.0f, 33.0f, 10.0f, 11.0f, 12.0f});
}

/** Two mesh draws, the second differing only as `vary` says. How many draws survive. */
u32 drawsAfterMerge(const std::function<void(BatchDrawKey&, u32&)>& vary) {
    Harness h;
    const BatchDrawKey base = meshKey(5);
    BatchDrawKey second = base;
    u32 indexOffset = 0;
    vary(second, indexOffset);

    for (const auto& [key, at] : { std::pair{base, 0u}, std::pair{second, indexOffset} }) {
        const u32 rec = h.pool.allocVertices(LayoutId::MeshInstance, key.instanceStride);
        pushBatchDraw(h.list, h.clips, rec, 0, at, 36, key);
    }
    h.list.finalize(h.pool);
    return h.list.mergedDrawCallCount();
}

TEST_CASE("finalize: two mesh draws alike but for one thing stay two draws") {
    // Each case varies ONE thing and leaves the pair adjacent in the sort, so
    // the check under test is the only thing that can separate them. A fixture
    // where something else also differs would pass with the check deleted.
    CHECK(drawsAfterMerge([](BatchDrawKey&, u32&) {}) == 1);  // the control

    CHECK(drawsAfterMerge([](BatchDrawKey& k, u32&) {
        k.vertexBuffer = BufferHandle{6};                     // another mesh
    }) == 2);
    CHECK(drawsAfterMerge([](BatchDrawKey& k, u32&) {
        k.indexBuffer = BufferHandle{106};
    }) == 2);
    CHECK(drawsAfterMerge([](BatchDrawKey&, u32& indexOffset) {
        indexOffset = 36;                                     // another range of it
    }) == 2);
    CHECK(drawsAfterMerge([](BatchDrawKey& k, u32&) {
        k.textureId = 42;                                     // samplers are per draw
    }) == 2);
    CHECK(drawsAfterMerge([](BatchDrawKey& k, u32&) {
        k.materialId = 9;
    }) == 2);
    CHECK(drawsAfterMerge([](BatchDrawKey& k, u32&) {
        k.cull = 1;
    }) == 2);
    CHECK(drawsAfterMerge([](BatchDrawKey& k, u32&) {
        k.shaderId = 12;
    }) == 2);

    // Order-dependence, one property at a time. Each of these alone makes the
    // second draw one whose result depends on when it happens, and the head is
    // the opaque one — so a check that asks only about ITSELF passes them all.
    CHECK(drawsAfterMerge([](BatchDrawKey& k, u32&) {
        k.blend = BlendMode::Normal;
    }) == 2);
    CHECK(drawsAfterMerge([](BatchDrawKey& k, u32&) {
        k.depthTest = false;
    }) == 2);
    CHECK(drawsAfterMerge([](BatchDrawKey& k, u32&) {
        k.depthWrite = false;
    }) == 2);
}

TEST_CASE("finalize: the HEAD's own order-dependence stops a merge too") {
    // A material can say `blend: none, depthWrite: false`: nothing reads what
    // is behind and nothing records what is in front, so the last draw wins.
    // Submitted first it is the head, which only a check on ITS state refuses.
    Harness h;
    BatchDrawKey unordered = meshKey(5);
    unordered.depthWrite = false;
    pushMeshInstance(h, unordered, 1.0f, 20.0f);
    pushMeshInstance(h, meshKey(5), 2.0f, 20.0f);

    h.list.finalize(h.pool);
    CHECK(h.list.mergedDrawCallCount() == 2);
}

TEST_CASE("finalize: a blended mesh keeps its own draw, because its order is the result") {
    Harness h;
    BatchDrawKey key = meshKey(5);
    key.stage = RenderStage::Transparent;
    key.blend = BlendMode::Normal;
    key.depthWrite = false;
    pushMeshInstance(h, key, 1.0f, 10.0f);
    pushMeshInstance(h, key, 2.0f, 20.0f);

    h.list.finalize(h.pool);
    CHECK(h.list.mergedDrawCallCount() == 2);
}

TEST_CASE("finalize: an opaque head does not swallow a blended draw of the same mesh") {
    // The asymmetric case, and the one a pixel gate caught: asking only whether
    // THIS draw is opaque lets an opaque head absorb a blended sibling and paint
    // it with the head's own state — the blended one then hides what is behind it.
    Harness h;
    pushMeshInstance(h, meshKey(5), 1.0f, 20.0f);

    // Same stage on purpose — what MeshPlugin submits when one of two meshes
    // has `opaque` off, and what puts the pair next to each other. Giving the
    // blended one its own stage would sort them apart and prove nothing.
    BatchDrawKey blended = meshKey(5);
    blended.blend = BlendMode::Normal;
    blended.depthTest = false;
    pushMeshInstance(h, blended, 2.0f, 10.0f);

    h.list.finalize(h.pool);
    CHECK(h.list.mergedDrawCallCount() == 2);
}

TEST_CASE("finalize: a skinned mesh keeps its own draw, because a pose is per draw") {
    Harness h;
    BatchDrawKey key = meshKey(5);
    key.instanceStride = 4;
    key.skinCount = 2;
    key.skinOffset = 0;
    pushMeshInstance(h, key, 1.0f);
    pushMeshInstance(h, key, 2.0f);

    h.list.finalize(h.pool);
    CHECK(h.list.mergedDrawCallCount() == 2);
}

TEST_CASE("execute: a merged mesh draw asks the device for its instances in one call") {
    Harness h;
    BatchDrawKey key = meshKey(5);
    for (int i = 0; i < 4; ++i) pushMeshInstance(h, key, static_cast<f32>(i));

    h.list.finalize(h.pool);
    h.pool.upload();
    MaterialStore materials;
    h.list.execute(h.device, h.pool, materials, 1);

    CHECK(h.device.drawElementsInstancedCalls == 1);
    CHECK(h.device.lastDrawInstanceCount == 4);
    CHECK(h.device.lastDrawIndexCount == 36);
}

TEST_CASE("execute: a sampling draw pins every sampler unit it does not use") {
    // A unit a draw leaves alone keeps what the draw BEFORE it bound, across passes
    // and frames. So a draw states its whole sampler block or none of it: one that
    // leaves unit 2 alone samples the shadow atlas a shadow pass is drawing into.
    Harness h;
    MaterialStore materials;
    const u32 white = 99;

    BatchDrawKey key = meshKey(5, /*textureId=*/7);  // albedo only: texture_count == 1
    pushMeshInstance(h, key, 1.0f);
    h.list.finalize(h.pool);
    h.pool.upload();
    h.list.execute(h.device, h.pool, materials, white);

    u32 boundAt[MAX_CMD_TEXTURE_SLOTS] = {};
    bool seen[MAX_CMD_TEXTURE_SLOTS] = {};
    bool record = false;
    for (const auto& [unit, tex] : h.device.bindLog) {
        // The frame's per-object record rides its own unit above the draw's eight.
        if (unit == MESH_INSTANCE_TEXTURE_UNIT) {
            record = true;
            continue;
        }
        REQUIRE(unit < MAX_CMD_TEXTURE_SLOTS);
        boundAt[unit] = static_cast<u32>(tex);
        seen[unit] = true;
    }
    CHECK(record);
    for (u32 unit = 0; unit < MAX_CMD_TEXTURE_SLOTS; ++unit) {
        CHECK(seen[unit]);  // no unit left to whatever ran before
        CHECK(boundAt[unit] == (unit == 0 ? 7u : white));
    }
}

TEST_CASE("execute: a textureless stream declares no sampler and is left alone") {
    // The other half of the same rule: the shape stream samples nothing, so it
    // declares nothing, so there is no binding for stale state to land in.
    Harness h;
    MaterialStore materials;

    TestShapeVertex sverts[4] = {};
    BatchDrawKey key = quadKey(0);
    key.layoutId = LayoutId::Shape;
    appendIndexedDraw(h.pool, h.list, h.clips, sverts, 4, BATCH_QUAD_INDICES, 6, key);

    h.list.finalize(h.pool);
    h.pool.upload();
    h.list.execute(h.device, h.pool, materials, 99);

    CHECK(h.device.bindLog.empty());
}

TEST_CASE("clip state is stamped onto commands from every stream") {
    Harness h;
    Entity clipped{5};
    h.clips.setScissor(clipped.id(), 1, 2, 3, 4);

    TestShapeVertex sverts[4] = {};
    BatchDrawKey key = quadKey(0);
    key.layoutId = LayoutId::Shape;
    key.entity = clipped;
    appendIndexedDraw(h.pool, h.list, h.clips, sverts, 4, BATCH_QUAD_INDICES, 6, key);

    REQUIRE(h.list.commandCount() == 1);
    const DrawCommand& cmd = h.list.command(0);
    CHECK((cmd.state_flags & CMD_STATE_SCISSOR) != 0);
    CHECK(cmd.scissor.x == 1);
    CHECK(cmd.scissor.h == 4);
}

TEST_CASE("execute: indexed and instanced commands dispatch through the device") {
    Harness h;
    MaterialStore materials;

    BatchVertex quad[4] = {};
    appendQuad(h.pool, h.list, h.clips, quad, quadKey(42));

    BatchDrawKey inst = quadKey(42);
    inst.layoutId = LayoutId::ParticleInstance;
    inst.instanceCount = 5;
    pushBatchDraw(h.list, h.clips, 0, 0, 0, 6, inst);

    h.list.finalize(h.pool);
    h.pool.upload();
    h.list.execute(h.device, h.pool, materials);

    CHECK(h.device.drawElementsCalls == 1);
    CHECK(h.device.drawElementsInstancedCalls == 1);
    CHECK(h.device.lastDrawInstanceCount == 5);
    CHECK(h.device.setPipelineCalls == 2);
}

// The sort key ranks layer above stage, and both of these pin that down. Swapping the
// two fields back (stage on top, the classic 3D pipeline order) flips the first check
// and leaves the second passing — which is exactly the failure the old layout had:
// correct inside a layer, and silently wrong across layers. Every other case in this
// file submits Transparent only, so neither would have been caught here.
TEST_CASE("sort order: a lower sorting layer draws first even when a higher one is opaque") {
    Harness h;
    BatchVertex quad[4] = {};

    BatchDrawKey opaqueAbove = quadKey(50, /*layer=*/5);
    opaqueAbove.stage = RenderStage::Opaque;
    // A different shader only keeps the two from coalescing, so their order stays
    // observable; shader ranks below both fields under test.
    opaqueAbove.shaderId = 8;
    appendQuad(h.pool, h.list, h.clips, quad, opaqueAbove);
    appendQuad(h.pool, h.list, h.clips, quad, quadKey(51, /*layer=*/3));

    h.list.finalize(h.pool);

    REQUIRE(h.list.mergedDrawCallCount() == 2);
    CHECK(h.list.command(0).texture_ids[0] == 51);
    CHECK(h.list.command(1).texture_ids[0] == 50);
}

TEST_CASE("sort order: inside one layer, opaque draws before blended") {
    Harness h;
    BatchVertex quad[4] = {};

    appendQuad(h.pool, h.list, h.clips, quad, quadKey(60, /*layer=*/4));
    BatchDrawKey opaque = quadKey(61, /*layer=*/4);
    opaque.stage = RenderStage::Opaque;
    opaque.shaderId = 8;
    appendQuad(h.pool, h.list, h.clips, quad, opaque);

    h.list.finalize(h.pool);

    REQUIRE(h.list.mergedDrawCallCount() == 2);
    CHECK(h.list.command(0).texture_ids[0] == 61);
    CHECK(h.list.command(1).texture_ids[0] == 60);
}

// Opaque is a blend MODE, not a switch beside one — so "no blending" has to survive
// the trip from the draw's blend field to the pipeline the device is handed. Without
// this the scene path hardcoded blendEnabled, and an opaque material silently kept
// reading the destination it was asking to replace.
TEST_CASE("execute: BlendMode::None turns blending off in the resolved pipeline") {
    Harness h;
    MaterialStore materials;
    BatchVertex quad[4] = {};

    BatchDrawKey key = quadKey(42);
    key.blend = BlendMode::None;
    appendQuad(h.pool, h.list, h.clips, quad, key);
    h.list.finalize(h.pool);
    h.pool.upload();
    h.list.execute(h.device, h.pool, materials);

    CHECK(h.device.lastPipelineDesc.blend == BlendMode::None);
    CHECK(h.device.lastPipelineDesc.blendEnabled == false);
}

TEST_CASE("execute: every other blend mode leaves blending on") {
    Harness h;
    MaterialStore materials;
    BatchVertex quad[4] = {};

    appendQuad(h.pool, h.list, h.clips, quad, quadKey(42));
    h.list.finalize(h.pool);
    h.pool.upload();
    h.list.execute(h.device, h.pool, materials);

    CHECK(h.device.lastPipelineDesc.blend == BlendMode::Normal);
    CHECK(h.device.lastPipelineDesc.blendEnabled == true);
}

// Two draws that agree on everything the merge used to look at, and disagree on
// whether they write depth. Before a layer could derive depth state from its stage,
// equal material_id implied equal depth state and this could not arise; now it can,
// and merging them would hand one of them the other's depth behaviour.
TEST_CASE("finalize: draws with different depth state never coalesce") {
    Harness h;
    BatchVertex quad[4] = {};

    BatchDrawKey writes = quadKey(42);
    writes.depthWrite = true;
    appendQuad(h.pool, h.list, h.clips, quad, writes);

    BatchDrawKey reads = quadKey(43);
    reads.depthWrite = false;
    appendQuad(h.pool, h.list, h.clips, quad, reads);

    h.list.finalize(h.pool);

    CHECK(h.list.mergedDrawCallCount() == 2);
}

// A depth layer resolves its own stage and depth state from the one physical fact
// that decides them: whether the draw reads the destination. Nobody declares this
// per material, because getting it wrong is not a preference — a blended draw that
// writes depth clips its neighbours into black edges.
TEST_CASE("depth layer: an opaque draw writes depth and lands in the Opaque stage") {
    Harness h;
    h.list.setDepthMask(1u << 4);
    BatchVertex quad[4] = {};

    BatchDrawKey key = quadKey(42, /*layer=*/4);
    key.blend = BlendMode::None;
    appendQuad(h.pool, h.list, h.clips, quad, key);

    REQUIRE(h.list.commandCount() == 1);
    CHECK(h.list.command(0).stage == RenderStage::Opaque);
    CHECK(h.list.command(0).depth_test == true);
    CHECK(h.list.command(0).depth_write == true);
}

TEST_CASE("depth layer: a blended draw tests depth but never writes it") {
    Harness h;
    h.list.setDepthMask(1u << 4);
    BatchVertex quad[4] = {};

    appendQuad(h.pool, h.list, h.clips, quad, quadKey(42, /*layer=*/4));

    REQUIRE(h.list.commandCount() == 1);
    CHECK(h.list.command(0).stage == RenderStage::Transparent);
    CHECK(h.list.command(0).depth_test == true);
    CHECK(h.list.command(0).depth_write == false);
}

// The whole point of making it a layer property: a project that declares no depth
// layer must render exactly as it did, down to the pipeline state.
TEST_CASE("depth layer: a painter layer is untouched by the opt-in") {
    Harness h;
    h.list.setDepthMask(1u << 4);
    BatchVertex quad[4] = {};

    BatchDrawKey key = quadKey(42, /*layer=*/5);  // not the depth layer
    key.blend = BlendMode::None;
    appendQuad(h.pool, h.list, h.clips, quad, key);

    REQUIRE(h.list.commandCount() == 1);
    CHECK(h.list.command(0).stage == RenderStage::Transparent);
    CHECK(h.list.command(0).depth_test == false);
}

// Y-sort is a depth projected from world Y; real depth is the thing itself. A layer
// claiming both has said two contradictory things, and y-sort wins so that a project
// which had it keeps rendering as it did.
TEST_CASE("depth layer: y-sort wins when a layer declares both") {
    Harness h;
    h.list.setYSortMask(1u << 4);
    h.list.setDepthMask(1u << 4);

    CHECK(h.list.layerOrder(4) == DrawList::LayerOrder::YSort);
    CHECK(h.list.layerOrder(5) == DrawList::LayerOrder::Painter);
}

// A layer painted in tree order stacks its draws as their entities stand in the hierarchy walk, whatever they are drawn with: a label
// (one shader) of a panel underneath must land below the image (another) of the panel above, which shader order cannot give.
TEST_CASE("tree layer: draws stack by their entity's place in the walk, not by shader") {
    Harness h;
    h.list.setTreeMask(1u << 4);
    // entity index 1 stands later in the walk than index 2
    h.list.setTreeSequence({0u, 2u, 1u});
    BatchVertex quad[4] = {};

    BatchDrawKey later = quadKey(1, /*layer=*/4);
    later.entity = Entity::fromRaw(1);
    later.shaderId = 3;   // shader order alone would draw this one first
    BatchDrawKey earlier = quadKey(2, /*layer=*/4);
    earlier.entity = Entity::fromRaw(2);
    earlier.shaderId = 9;

    appendQuad(h.pool, h.list, h.clips, quad, later);
    appendQuad(h.pool, h.list, h.clips, quad, earlier);
    h.list.finalize(h.pool);

    CHECK(h.list.layerOrder(4) == DrawList::LayerOrder::Tree);
    REQUIRE(h.list.mergedDrawCallCount() == 2);
    CHECK(h.list.command(0).texture_ids[0] == 2);
    CHECK(h.list.command(1).texture_ids[0] == 1);
}

// Y-sort is a stated order of its own; a layer asking for both keeps the one it had before tree order existed.
TEST_CASE("tree layer: y-sort wins when a layer declares both") {
    Harness h;
    h.list.setYSortMask(1u << 4);
    h.list.setTreeMask(1u << 4);
    CHECK(h.list.layerOrder(4) == DrawList::LayerOrder::YSort);
}

// ─── Order within a layer ────────────────────────────────────────────────────
// The author's explicit answer to "what is on top of what", inside one layer. Each case
// below is one the layer's own ordering gets wrong on purpose, so it measures an override.

// Each pair gets two shaders, which keeps them from coalescing into one multi-texture
// draw and leaves their order observable. Shader ranks below every field under test.

TEST_CASE("order: a higher order draws on top of a nearer sprite") {
    Harness h;
    BatchVertex quad[4] = {};

    BatchDrawKey nearer = quadKey(1, /*layer=*/3);
    nearer.depth = 50.0f;   // nearest — depth alone would put it last
    BatchDrawKey farther = quadKey(2, /*layer=*/3);
    farther.depth = -50.0f;
    farther.order = 1;
    farther.shaderId = 8;

    appendQuad(h.pool, h.list, h.clips, quad, nearer);
    appendQuad(h.pool, h.list, h.clips, quad, farther);
    h.list.finalize(h.pool);

    REQUIRE(h.list.mergedDrawCallCount() == 2);
    CHECK(h.list.command(0).texture_ids[0] == 1);
    CHECK(h.list.command(1).texture_ids[0] == 2);
}

// The gap this field was added for. A y-sorted layer drops z from the key entirely, so
// before this there was NO way to pin a draw inside one — a shadow that must stay under
// its owner had only the owner's own Y to argue with.
TEST_CASE("order: inside a y-sorted layer, a stated order beats world Y") {
    Harness h;
    h.list.setYSortMask(1u << 4);
    BatchVertex quad[4] = {};

    // Lower Y draws last under y-sort, so this one would land on top unaided.
    BatchDrawKey low = quadKey(1, /*layer=*/4);
    low.y = -100.0f;
    BatchDrawKey high = quadKey(2, /*layer=*/4);
    high.y = 100.0f;
    high.order = 1;
    high.shaderId = 8;

    appendQuad(h.pool, h.list, h.clips, quad, low);
    appendQuad(h.pool, h.list, h.clips, quad, high);
    h.list.finalize(h.pool);

    REQUIRE(h.list.mergedDrawCallCount() == 2);
    CHECK(h.list.command(0).texture_ids[0] == 1);
    CHECK(h.list.command(1).texture_ids[0] == 2);
}

// Y-sort still orders everything the author did not speak for. Without this, a field
// that simply disabled y-sort would pass every other case here.
TEST_CASE("order: equal orders leave y-sort to decide") {
    Harness h;
    h.list.setYSortMask(1u << 4);
    BatchVertex quad[4] = {};

    BatchDrawKey low = quadKey(1, /*layer=*/4);  low.y = -100.0f;
    BatchDrawKey high = quadKey(2, /*layer=*/4); high.y = 100.0f; high.shaderId = 8;
    low.order = high.order = 5;                  // stated, and stated the same

    appendQuad(h.pool, h.list, h.clips, quad, low);
    appendQuad(h.pool, h.list, h.clips, quad, high);
    h.list.finalize(h.pool);

    REQUIRE(h.list.mergedDrawCallCount() == 2);
    CHECK(h.list.command(0).texture_ids[0] == 2);  // higher Y is further back
    CHECK(h.list.command(1).texture_ids[0] == 1);
}

// An order is a promise about one layer's contents, never about the layer itself.
TEST_CASE("order: the largest order never escapes its own layer") {
    Harness h;
    BatchVertex quad[4] = {};

    BatchDrawKey shouted = quadKey(1, /*layer=*/3);
    shouted.order = 127;
    BatchDrawKey above = quadKey(2, /*layer=*/4);
    above.order = -128;
    above.shaderId = 8;

    appendQuad(h.pool, h.list, h.clips, quad, shouted);
    appendQuad(h.pool, h.list, h.clips, quad, above);
    h.list.finalize(h.pool);

    REQUIRE(h.list.mergedDrawCallCount() == 2);
    CHECK(h.list.command(0).layer == 3);
    CHECK(h.list.command(1).layer == 4);
}

// Biased, not masked: -1 has to land below 0 rather than wrapping to the top of the
// field, which is what a two's-complement cast into the key would have done.
TEST_CASE("order: a negative order sinks below an unstated one") {
    Harness h;
    BatchVertex quad[4] = {};

    BatchDrawKey plain = quadKey(1, /*layer=*/3);
    BatchDrawKey behind = quadKey(2, /*layer=*/3);
    behind.order = -1;
    behind.shaderId = 8;

    appendQuad(h.pool, h.list, h.clips, quad, plain);
    appendQuad(h.pool, h.list, h.clips, quad, behind);
    h.list.finalize(h.pool);

    REQUIRE(h.list.mergedDrawCallCount() == 2);
    CHECK(h.list.command(0).texture_ids[0] == 2);
    CHECK(h.list.command(1).texture_ids[0] == 1);
}

// Clamped, not wrapped. A project ported from an engine with a wider range keeps the
// SIGN of what it asked for: "far on top" degrades to "on top", never to "behind".
TEST_CASE("order: an order past the range pins to the end it ran past") {
    Harness h;
    BatchVertex quad[4] = {};

    BatchDrawKey huge = quadKey(1, /*layer=*/3);
    huge.order = 32000;
    BatchDrawKey tiny = quadKey(2, /*layer=*/3);
    tiny.order = -32000;
    tiny.shaderId = 8;

    appendQuad(h.pool, h.list, h.clips, quad, huge);
    appendQuad(h.pool, h.list, h.clips, quad, tiny);
    h.list.finalize(h.pool);

    REQUIRE(h.list.mergedDrawCallCount() == 2);
    CHECK(h.list.command(0).texture_ids[0] == 2);
    CHECK(h.list.command(1).texture_ids[0] == 1);
}

// Order outranks stage for the same reason layer does: it is a promise the author made,
// and a stage is only how a layer groups what it holds. An opaque draw the author put
// underneath must stay underneath, early-z or not.
TEST_CASE("order: a blended draw ordered below an opaque one still draws first") {
    Harness h;
    BatchVertex quad[4] = {};

    BatchDrawKey blended = quadKey(1, /*layer=*/3);
    blended.order = -1;
    BatchDrawKey opaque = quadKey(2, /*layer=*/3);
    opaque.stage = RenderStage::Opaque;
    opaque.shaderId = 8;

    appendQuad(h.pool, h.list, h.clips, quad, opaque);
    appendQuad(h.pool, h.list, h.clips, quad, blended);
    h.list.finalize(h.pool);

    REQUIRE(h.list.mergedDrawCallCount() == 2);
    CHECK(h.list.command(0).texture_ids[0] == 1);
    CHECK(h.list.command(1).texture_ids[0] == 2);
}

// BlendMode::None is 9 and the key's blend field is 3 bits, so unmasked it set a bit in
// the SHADER field above it. Painter-ordered on purpose: a depth layer routes a None
// blend to the Opaque stage, never reaching the blended packing where the spill showed.
TEST_CASE("sort key: an opaque blend mode cannot reach the shader field") {
    Harness h;
    BatchVertex quad[4] = {};

    BatchDrawKey none = quadKey(1, /*layer=*/3);
    none.blend = BlendMode::None;
    BatchDrawKey normal = quadKey(2, /*layer=*/3);

    // Same shader, same depth, same everything the key ranks above blend: whatever
    // separates them is the blend field, and it may not reach past its own 3 bits.
    CHECK((DrawCommand::buildSortKey(RenderStage::Transparent, 3, none.shaderId,
                                     BlendMode::None, 0, 0.0f) >> 10)
          == (DrawCommand::buildSortKey(RenderStage::Transparent, 3, normal.shaderId,
                                        BlendMode::Normal, 0, 0.0f) >> 10));

    appendQuad(h.pool, h.list, h.clips, quad, none);
    appendQuad(h.pool, h.list, h.clips, quad, normal);
    h.list.finalize(h.pool);
    REQUIRE(h.list.mergedDrawCallCount() == 2);
}

// ─── Stencil mask ordering ───────────────────────────────────────────────────
// A stencil write must precede the draws that test it, and the sort key holds no
// clip state. The layer does it: UI pre-order puts a parent below its descendants.

TEST_CASE("stencil: the mask outranks its content even when material and depth fight it") {
    Harness h;
    BatchVertex quad[4] = {};
    Entity maskEntity{11};
    Entity contentEntity{12};

    // Worst case the UI tree can produce: the mask is the parent (lower uiOrder →
    // lower layer) but loses on every field below layer.
    BatchDrawKey mask = quadKey(1, /*layer=*/1000);
    mask.entity = maskEntity;
    mask.materialId = 90000;   // sorts after the content's material
    mask.depth = 100.0f;       // nearest — would sort last within a transparent layer
    h.clips.setStencilMask(maskEntity.id(), 1);

    BatchDrawKey content = quadKey(2, /*layer=*/1001);
    content.entity = contentEntity;
    content.materialId = 1;
    content.depth = -100.0f;
    h.clips.setStencilTest(contentEntity.id(), 1);

    // Submitted content-first, so only the sort can put them right.
    appendQuad(h.pool, h.list, h.clips, quad, content);
    appendQuad(h.pool, h.list, h.clips, quad, mask);
    h.list.finalize(h.pool);

    REQUIRE(h.list.mergedDrawCallCount() == 2);
    CHECK((h.list.command(0).state_flags & CMD_STATE_STENCIL_WRITE) != 0);
    CHECK((h.list.command(1).state_flags & CMD_STATE_STENCIL_TEST) != 0);
}

TEST_CASE("stencil: a nested mask still writes before the content it clips") {
    Harness h;
    BatchVertex quad[4] = {};
    Entity outer{20}, inner{21}, leaf{22};

    // outer(layer 1000) → inner mask(1001) → leaf(1002), each on its own material.
    BatchDrawKey outerKey = quadKey(1, 1000);
    outerKey.entity = outer;
    outerKey.materialId = 7;
    h.clips.setStencilMask(outer.id(), 1);

    BatchDrawKey innerKey = quadKey(2, 1001);
    innerKey.entity = inner;
    innerKey.materialId = 300;
    h.clips.setStencilMask(inner.id(), 2);

    BatchDrawKey leafKey = quadKey(3, 1002);
    leafKey.entity = leaf;
    leafKey.materialId = 4;
    h.clips.setStencilTest(leaf.id(), 2);

    appendQuad(h.pool, h.list, h.clips, quad, leafKey);
    appendQuad(h.pool, h.list, h.clips, quad, innerKey);
    appendQuad(h.pool, h.list, h.clips, quad, outerKey);
    h.list.finalize(h.pool);

    REQUIRE(h.list.mergedDrawCallCount() == 3);
    CHECK(h.list.command(0).stencil_ref == 1);
    CHECK((h.list.command(0).state_flags & CMD_STATE_STENCIL_WRITE) != 0);
    CHECK(h.list.command(1).stencil_ref == 2);
    CHECK((h.list.command(1).state_flags & CMD_STATE_STENCIL_WRITE) != 0);
    CHECK(h.list.command(2).stencil_ref == 2);
    CHECK((h.list.command(2).state_flags & CMD_STATE_STENCIL_TEST) != 0);
}

TEST_CASE("UI stencil restores parents between siblings without duplicating geometry") {
    Harness h;
    BatchVertex quad[4] = {};
    const Entity outer{201}, first{202}, second{203}, leafA{204}, leafB{205}, tail{206};
    h.clips.setUIStencilMask(outer.id(), 1);
    h.clips.setUIStencilMask(first.id(), 2);
    h.clips.setUIStencilMask(second.id(), 2);
    h.clips.setUIStencilTest(leafA.id(), 2);
    h.clips.setUIStencilTest(leafB.id(), 2);
    h.clips.setUIStencilTest(tail.id(), 1);
    // Sprite masks occupy the lower references; nested UI must never accept
    // their pixels outside its own root.
    h.clips.reserveSpriteStencilReferences(7);
    i32 layer = 0;
    for (Entity entity : {outer, first, leafA, second, leafB, tail}) {
        auto key = quadKey(1, layer++);
        key.entity = entity;
        appendQuad(h.pool, h.list, h.clips, quad, key);
    }
    const u32 vertexBytes = h.pool.vertexBytesUsed(LayoutId::Batch);
    const u32 indices = h.pool.indicesUsed(LayoutId::Batch);
    h.list.finalize(h.pool);
    REQUIRE(h.list.mergedDrawCallCount() == 9);
    const GfxStencilMode modes[] = {GfxStencilMode::Write, GfxStencilMode::Increment,
        GfxStencilMode::Test, GfxStencilMode::Decrement, GfxStencilMode::Increment,
        GfxStencilMode::Test, GfxStencilMode::Decrement, GfxStencilMode::Test, GfxStencilMode::Zero};
    const i32 refs[] = {8, 8, 9, 9, 8, 9, 9, 8, 8};
    for (u32 i = 0; i < 9; ++i) {
        const auto& command = h.list.command(i);
        CHECK(stencilModeOf(command.state_flags) == modes[i]);
        CHECK(command.stencil_ref == refs[i]);
        if (writesStencil(modes[i])) {
            CHECK_FALSE(command.depth_test);
            CHECK_FALSE(command.depth_write);
        }
    }
    CHECK(h.list.command(3).index_offset == h.list.command(1).index_offset);
    CHECK(h.list.command(6).index_offset == h.list.command(4).index_offset);
    CHECK(h.list.command(8).index_offset == h.list.command(0).index_offset);
    CHECK(h.pool.vertexBytesUsed(LayoutId::Batch) == vertexBytes);
    CHECK(h.pool.indicesUsed(LayoutId::Batch) == indices);
}

TEST_CASE("UI stencil keeps every piece of a mask and supports 255 nested levels") {
    SUBCASE("multiple commands contribute to one mask") {
        Harness h;
        BatchVertex quad[4] = {};
        h.clips.setUIStencilMask(301, 1);
        h.clips.setUIStencilTest(302, 1);
        for (u32 i = 0; i < 3; ++i) {
            auto key = quadKey(i + 1, static_cast<i32>(i));
            key.entity = Entity{i < 2 ? 301u : 302u};
            appendQuad(h.pool, h.list, h.clips, quad, key);
        }
        h.list.finalize(h.pool);
        REQUIRE(h.list.mergedDrawCallCount() == 5);
        CHECK(stencilModeOf(h.list.command(0).state_flags) == GfxStencilMode::Write);
        CHECK(stencilModeOf(h.list.command(1).state_flags) == GfxStencilMode::Write);
        CHECK(stencilModeOf(h.list.command(2).state_flags) == GfxStencilMode::Test);
        CHECK(stencilModeOf(h.list.command(3).state_flags) == GfxStencilMode::Zero);
        CHECK(stencilModeOf(h.list.command(4).state_flags) == GfxStencilMode::Zero);
        CHECK(h.list.command(0).texture_ids[0] == h.list.command(4).texture_ids[0]);
        CHECK(h.list.command(1).texture_ids[0] == h.list.command(3).texture_ids[0]);
        const auto* vertices = reinterpret_cast<const BatchVertex*>(h.pool.vertexData(LayoutId::Batch));
        for (u32 vertex = 0; vertex < 8; ++vertex) CHECK(vertices[vertex].texIndex == 0);
    }
    SUBCASE("all eight stencil planes remain available") {
        Harness h;
        BatchVertex quad[4] = {};
        for (u32 depth = 1; depth <= 255; ++depth) {
            h.clips.setUIStencilMask(depth, static_cast<i32>(depth));
            auto key = quadKey(1, static_cast<i32>(depth));
            key.entity = Entity{depth};
            appendQuad(h.pool, h.list, h.clips, quad, key);
        }
        h.clips.setUIStencilTest(256, 255);
        auto key = quadKey(1, 256);
        key.entity = Entity{256};
        appendQuad(h.pool, h.list, h.clips, quad, key);
        h.list.finalize(h.pool);
        REQUIRE(h.list.mergedDrawCallCount() == 511);
        CHECK(h.list.command(254).stencil_ref == 254);
        CHECK(h.list.command(255).stencil_ref == 255);
        CHECK(stencilModeOf(h.list.command(256).state_flags) == GfxStencilMode::Decrement);
        CHECK(h.list.command(256).stencil_ref == 255);
        CHECK(stencilModeOf(h.list.command(510).state_flags) == GfxStencilMode::Zero);
    }
    SUBCASE("missing mask geometry does not expose stale stencil values") {
        Harness h;
        BatchVertex quad[4] = {};
        h.clips.setUIStencilTest(401, 1);
        auto key = quadKey(1);
        key.entity = Entity{401};
        appendQuad(h.pool, h.list, h.clips, quad, key);
        h.list.finalize(h.pool);
        CHECK(h.list.mergedDrawCallCount() == 0);
    }
    SUBCASE("shared stencil capacity clips overflow instead of aliasing") {
        ClipState clips;
        clips.setUIStencilMask(501, 254);
        clips.setUIStencilTest(502, 255);
        clips.reserveSpriteStencilReferences(1);
        CHECK(clips.getEntry(501)->stencil_ref == 255);
        CHECK_FALSE(clips.isEmptyScissor(Entity{501}));
        CHECK(clips.isEmptyScissor(Entity{502}));
    }
}

// Where the guarantee stops. Nothing the engine emits puts a mask and its content
// on one layer; a caller reaching for renderer_setEntityStencilMask directly can.
TEST_CASE("stencil: on one layer, material — not submission or depth — decides") {
    Harness h;
    BatchVertex quad[4] = {};
    Entity a{31}, b{32};

    BatchDrawKey writer = quadKey(1, /*layer=*/1000);
    writer.entity = a;
    writer.materialId = 90000;
    h.clips.setStencilMask(a.id(), 1);

    BatchDrawKey tester = quadKey(2, /*layer=*/1000);
    tester.entity = b;
    tester.materialId = 1;
    h.clips.setStencilTest(b.id(), 1);

    appendQuad(h.pool, h.list, h.clips, quad, writer);
    appendQuad(h.pool, h.list, h.clips, quad, tester);
    h.list.finalize(h.pool);

    REQUIRE(h.list.mergedDrawCallCount() == 2);
    // The lower material wins, so the test lands FIRST — the mask is written after
    // the thing it was supposed to clip.
    CHECK((h.list.command(0).state_flags & CMD_STATE_STENCIL_TEST) != 0);
    CHECK((h.list.command(1).state_flags & CMD_STATE_STENCIL_WRITE) != 0);
}

// ─── Blended depth ordering ──────────────────────────────────────────────────
// A blended draw composites onto what is already there, so back-to-front IS the
// result. Material may not outrank it — batching is the thing that yields.

TEST_CASE("transparent: back-to-front holds across materials") {
    Harness h;
    BatchVertex quad[4] = {};

    // Camera looks down -z, so larger z is nearer and must land last.
    BatchDrawKey nearer = quadKey(1, /*layer=*/3);
    nearer.materialId = 1;          // lowest material — would have sorted first
    nearer.depth = 50.0f;

    BatchDrawKey middle = quadKey(2, /*layer=*/3);
    middle.materialId = 90000;
    middle.depth = 0.0f;

    BatchDrawKey farther = quadKey(3, /*layer=*/3);
    farther.materialId = 500;
    farther.depth = -50.0f;

    appendQuad(h.pool, h.list, h.clips, quad, nearer);
    appendQuad(h.pool, h.list, h.clips, quad, middle);
    appendQuad(h.pool, h.list, h.clips, quad, farther);
    h.list.finalize(h.pool);

    REQUIRE(h.list.mergedDrawCallCount() == 3);
    CHECK(h.list.command(0).texture_ids[0] == 3);  // far
    CHECK(h.list.command(1).texture_ids[0] == 2);  // middle
    CHECK(h.list.command(2).texture_ids[0] == 1);  // near
}

TEST_CASE("transparent: equal depth still groups by material for the merge") {
    Harness h;
    BatchVertex quad[4] = {};

    BatchDrawKey a1 = quadKey(1, 3); a1.materialId = 7; a1.depth = 0.0f;
    BatchDrawKey b = quadKey(2, 3);  b.materialId = 8;  b.depth = 0.0f;
    // The same texture as a1: a material run carries one texture (its shader reads
    // slot 0 alone), so this pins the grouping, not a cross-texture merge.
    BatchDrawKey a2 = quadKey(1, 3); a2.materialId = 7; a2.depth = 0.0f;

    // Submitted adjacent so their index ranges stay contiguous — the merge needs
    // that as well as adjacency after the sort.
    appendQuad(h.pool, h.list, h.clips, quad, a1);
    appendQuad(h.pool, h.list, h.clips, quad, a2);
    appendQuad(h.pool, h.list, h.clips, quad, b);
    h.list.finalize(h.pool);

    REQUIRE(h.list.mergedDrawCallCount() == 2);
    CHECK(h.list.command(0).material_id == 7);
    CHECK(h.list.command(1).material_id == 8);
}

TEST_CASE("opaque: material still outranks depth, since order cannot change the result") {
    Harness h;
    BatchVertex quad[4] = {};

    BatchDrawKey a1 = quadKey(1, 3); a1.stage = RenderStage::Opaque;
    a1.blend = BlendMode::None; a1.materialId = 7; a1.depth = 100.0f;
    BatchDrawKey b = quadKey(2, 3);  b.stage = RenderStage::Opaque;
    b.blend = BlendMode::None;  b.materialId = 8;  b.depth = 0.0f;
    BatchDrawKey a2 = quadKey(1, 3); a2.stage = RenderStage::Opaque;  // a1's texture: see above
    a2.blend = BlendMode::None; a2.materialId = 7; a2.depth = -100.0f;

    appendQuad(h.pool, h.list, h.clips, quad, a1);
    appendQuad(h.pool, h.list, h.clips, quad, a2);
    appendQuad(h.pool, h.list, h.clips, quad, b);
    h.list.finalize(h.pool);

    // Both material-7 draws coalesce despite straddling material 8 in depth.
    REQUIRE(h.list.mergedDrawCallCount() == 2);
    CHECK(h.list.command(0).material_id == 7);
    CHECK(h.list.command(1).material_id == 8);
}

// 20 bits is sign + exponent + 11 mantissa bits, so the step is ~2^-11 of the
// exponent's range: about 0.004 around z=10. Closer than that shares a key and
// keeps submission order, which is the quantization talking, not a rule.
TEST_CASE("transparent: sorted index runs preserve distinct depth keys and quantized ties") {
    Harness h;
    BatchVertex quad[4] = {};
    // No material: the two textures are what tells the draws apart in the merged
    // run, and a material run keeps to one texture.

    BatchDrawKey nearer = quadKey(1, 3); nearer.depth = 10.01f;
    BatchDrawKey farther = quadKey(2, 3); farther.depth = 10.00f;
    appendQuad(h.pool, h.list, h.clips, quad, nearer);
    appendQuad(h.pool, h.list, h.clips, quad, farther);
    CHECK(h.list.command(1).sort_key < h.list.command(0).sort_key);
    h.list.finalize(h.pool);

    REQUIRE(h.list.mergedDrawCallCount() == 1);
    CHECK(h.list.command(0).texture_ids[0] == 2);
    CHECK(h.list.command(0).texture_ids[1] == 1);
    const auto* sorted = h.pool.indexData(LayoutId::Batch) + h.list.command(0).index_offset;
    CHECK(sorted[0] == 4);
    CHECK(sorted[6] == 0);

    Harness fine;
    BatchDrawKey a = quadKey(1, 3); a.depth = 10.001f;
    BatchDrawKey b = quadKey(2, 3); b.depth = 10.000f;
    appendQuad(fine.pool, fine.list, fine.clips, quad, a);
    appendQuad(fine.pool, fine.list, fine.clips, quad, b);
    CHECK(fine.list.command(0).sort_key == fine.list.command(1).sort_key);
    fine.list.finalize(fine.pool);
    CHECK(fine.list.mergedDrawCallCount() == 1);
    const auto* tied = fine.pool.indexData(LayoutId::Batch) + fine.list.command(0).index_offset;
    CHECK(tied[0] == 0);
    CHECK(tied[6] == 4);
}

// ─── Transient buffer growth ─────────────────────────────────────────────────
// A workload creeping upward each frame must not reallocate the GPU buffer every
// frame. The staging vectors double, and the GPU capacity follows them.

TEST_CASE("storage: idle streams allocate nothing and used streams survive recovery") {
    MockGfxDevice device;
    TransientBufferPool pool{device};
    pool.init(4096, 1024);
    CHECK(device.createBufferCalls == 0);
    CHECK(device.estimatedGpuBytes() == 0);
    for (auto layout : {LayoutId::Batch, LayoutId::Shape, LayoutId::Sky, LayoutId::ParticleInstance}) {
        CHECK(pool.layoutHandle(layout) != VertexLayoutHandle::Invalid);
        CHECK(pool.vertexStride(layout) > 0);
        CHECK(pool.vertexBuffer(layout) == BufferHandle::Invalid);
    }
    pool.allocVertices(LayoutId::Batch, 0);
    pool.allocIndices(LayoutId::Shape, 0);
    pool.upload();
    CHECK(device.createBufferCalls == 0);
    BatchVertex vertices[4] = {};
    const u32 indices[6] = {0, 1, 2, 2, 3, 0};
    pool.appendVertices(LayoutId::Batch, vertices, sizeof(vertices));
    pool.appendIndices(LayoutId::Batch, indices, 6);
    pool.upload();
    CHECK(device.createBufferCalls == 2);
    CHECK(device.estimatedGpuBytes() == 8192);
    const auto batch = pool.vertexBuffer(LayoutId::Batch);
    pool.beginFrame();
    pool.appendVertices(LayoutId::Batch, vertices, sizeof(vertices));
    pool.upload();
    CHECK(device.createBufferCalls == 2);
    CHECK(pool.vertexBuffer(LayoutId::Batch) == batch);
    std::vector<u8> particle(44);
    pool.appendVertices(LayoutId::ParticleInstance, particle.data(), 44);
    pool.upload();
    CHECK(device.createBufferCalls == 5);
    CHECK(device.estimatedGpuBytes() == 8192 + 4096 + 64 + 24);
    CHECK(pool.vertexBuffer(LayoutId::Sky) == BufferHandle::Invalid);
    CHECK(pool.vertexBuffer(LayoutId::Shape) == BufferHandle::Invalid);
    const auto storage = device.estimatedGpuBytes();
    device.notifyDeviceLost(GfxDeviceLostReason::ContextLost, "test");
    CHECK(device.estimatedGpuBytes() == 0);
    REQUIRE(device.recoverDevice());
    CHECK(device.estimatedGpuBytes() == storage);
    CHECK(pool.vertexBuffer(LayoutId::Batch) == batch);
    pool.upload();
    pool.shutdown();
    CHECK(device.estimatedGpuBytes() == 0);
    pool.init(4096, 1024);
    CHECK(device.estimatedGpuBytes() == 0);
    pool.shutdown();
}

TEST_CASE("growth: a slowly rising workload reallocates a handful of times, not per frame") {
    MockGfxDevice device;
    TransientBufferPool pool{device};
    pool.init(/*initialVertexBytes=*/4096, /*initialIndexCount=*/1024);

    const int FRAMES = 200;
    for (int f = 0; f < FRAMES; ++f) {
        pool.beginFrame();
        // Each frame asks for a little more than the last.
        const u32 quads = 64 + static_cast<u32>(f) * 8;
        BatchVertex quad[4] = {};
        for (u32 i = 0; i < quads; ++i) {
            pool.appendVertices(LayoutId::Batch, quad, sizeof(quad));
        }
        pool.upload();
    }

    // Doubling from 4KB, the whole run needs a bounded number of reallocations —
    // one per doubling per stream, not one per frame.
    CHECK(device.resizeBufferCalls < 32);
    CHECK(device.resizeBufferCalls > 0);   // it did have to grow
}

TEST_CASE("growth: a steady workload inside capacity never reallocates") {
    MockGfxDevice device;
    TransientBufferPool pool{device};
    pool.init(/*initialVertexBytes=*/1024 * 1024, /*initialIndexCount=*/64 * 1024);
    const int before = device.resizeBufferCalls;

    BatchVertex quad[4] = {};
    for (int f = 0; f < 100; ++f) {
        pool.beginFrame();
        for (int i = 0; i < 100; ++i) pool.appendVertices(LayoutId::Batch, quad, sizeof(quad));
        pool.upload();
    }
    CHECK_EQ(device.resizeBufferCalls, before);
}

// ============================================================================
// SortingGroup — the resolution pushBatchDraw does, asserted through the frame.
// The key's own field layout is test_sort_key's; what these hold is that the draw
// path ASKS the group rather than the member, everywhere a layer is consulted.
// ============================================================================

// The promise a per-sprite order cannot make. Two members straddle an outsider's
// order, and the outsider still may not come between them.
TEST_CASE("group: an outsider cannot be drawn between two members") {
    Harness h;
    h.list.setSortingGroup(11, {/*layer=*/3, /*order=*/5, false, 0});
    h.list.setSortingGroup(12, {/*layer=*/3, /*order=*/5, false, 0});
    BatchVertex quad[4] = {};

    BatchDrawKey low = quadKey(1, /*layer=*/9);   // the member's own layer is ignored
    low.order = -100;
    low.entity = Entity(11);
    BatchDrawKey high = quadKey(3, /*layer=*/9);
    high.order = 100;
    high.entity = Entity(12);
    // Ungrouped, and stated BETWEEN what the two members state for themselves. Sorting
    // by the member's own order — the pre-group behaviour — puts it in the middle.
    BatchDrawKey outsider = quadKey(2, /*layer=*/3);
    outsider.order = 6;
    outsider.shaderId = 8;

    appendQuad(h.pool, h.list, h.clips, quad, low);
    appendQuad(h.pool, h.list, h.clips, quad, outsider);
    appendQuad(h.pool, h.list, h.clips, quad, high);
    h.list.finalize(h.pool);

    REQUIRE(h.list.mergedDrawCallCount() == 2);
    // The two members adjacent and in their stated order, the outsider clear of both.
    CHECK(h.list.command(0).texture_ids[0] == 1);
    CHECK(h.list.command(0).texture_ids[1] == 3);
    CHECK(h.list.command(1).texture_ids[0] == 2);
    const auto* indices = h.pool.indexData(LayoutId::Batch) + h.list.command(0).index_offset;
    CHECK(indices[0] == 0);
    CHECK(indices[6] == 8);
    const auto members = h.list.runEntities(0);
    REQUIRE(members.size() == 2);
    CHECK(members[0] == Entity(11));
    CHECK(members[1] == Entity(12));
}

// Everything derived from a layer has to come from the GROUP's layer. A member whose
// own layer is y-sorted, in a group whose layer is not, must not y-sort.
TEST_CASE("group: the layer's rule is the group's, not the member's") {
    Harness h;
    h.list.setYSortMask(1u << 4);
    h.list.setSortingGroup(21, {/*layer=*/6, 0, false, 0});
    h.list.setSortingGroup(22, {/*layer=*/6, 0, false, 0});
    BatchVertex quad[4] = {};

    // The two rules must DISAGREE or this passes whichever ran. A stated order cannot make
    // them — it outranks both — so the orders are equal and depth and world Y are set to
    // opposite conclusions.
    BatchDrawKey backY = quadKey(1, /*layer=*/4);
    backY.y = -100.0f;      // y-sort: lower Y draws LAST
    backY.depth = -100.0f;  // painter: further draws FIRST
    backY.entity = Entity(21);
    BatchDrawKey frontY = quadKey(2, /*layer=*/4);
    frontY.y = 100.0f;
    frontY.depth = 100.0f;
    frontY.shaderId = 8;
    frontY.entity = Entity(22);

    appendQuad(h.pool, h.list, h.clips, quad, backY);
    appendQuad(h.pool, h.list, h.clips, quad, frontY);
    h.list.finalize(h.pool);

    REQUIRE(h.list.mergedDrawCallCount() == 2);
    // The group's layer is painter-ordered, so depth decides: y-sort would have
    // reversed exactly this pair.
    CHECK(h.list.command(0).texture_ids[0] == 1);
    CHECK(h.list.command(1).texture_ids[0] == 2);
}

// A group's members answer the camera's culling mask on the group's layer too —
// otherwise half a character disappears when a camera drops the layer it was rigged in.
TEST_CASE("group: culling reads the group's layer") {
    Harness h;
    h.list.setCullingMask(1u << 6);  // the group's layer only
    h.list.setSortingGroup(31, {/*layer=*/6, 0, false, 0});
    BatchVertex quad[4] = {};

    BatchDrawKey member = quadKey(1, /*layer=*/4);  // a layer this camera does not draw
    member.entity = Entity(31);
    BatchDrawKey ungrouped = quadKey(2, /*layer=*/4);

    appendQuad(h.pool, h.list, h.clips, quad, member);
    appendQuad(h.pool, h.list, h.clips, quad, ungrouped);
    h.list.finalize(h.pool);

    REQUIRE(h.list.mergedDrawCallCount() == 1);
    CHECK(h.list.command(0).texture_ids[0] == 1);
}

// A nested group is one block: its contents share the block's order and do not
// interleave with a sibling of the block, whatever they state for themselves.
TEST_CASE("group: a nested group's contents stay one block") {
    Harness h;
    h.list.setSortingGroup(41, {/*layer=*/3, 0, /*blockOrder=*/true, /*block=*/0});
    h.list.setSortingGroup(42, {/*layer=*/3, 0, /*blockOrder=*/true, /*block=*/0});
    h.list.setSortingGroup(43, {/*layer=*/3, 0, false, 0});
    BatchVertex quad[4] = {};

    // Two members of the inner block, stated far apart, and a sibling of the block
    // whose own order sits between those two statements.
    BatchDrawKey blockLow = quadKey(1, 3);
    blockLow.order = -50;
    blockLow.entity = Entity(41);
    BatchDrawKey sibling = quadKey(2, 3);
    sibling.order = 1;
    sibling.shaderId = 8;
    sibling.entity = Entity(43);
    BatchDrawKey blockHigh = quadKey(3, 3);
    blockHigh.order = 50;
    blockHigh.entity = Entity(42);

    appendQuad(h.pool, h.list, h.clips, quad, blockLow);
    appendQuad(h.pool, h.list, h.clips, quad, sibling);
    appendQuad(h.pool, h.list, h.clips, quad, blockHigh);
    h.list.finalize(h.pool);

    REQUIRE(h.list.mergedDrawCallCount() == 2);
    CHECK(h.list.command(1).texture_ids[0] == 2);  // the sibling is above the whole block
    const auto* indices = h.pool.indexData(LayoutId::Batch) + h.list.command(0).index_offset;
    CHECK(indices[0] == 0);
    CHECK(indices[6] == 8);
    const auto members = h.list.runEntities(0);
    REQUIRE(members.size() == 2);
    CHECK(members[0] == Entity(41));
    CHECK(members[1] == Entity(42));
}

// A group that is not there changes nothing — the field that decides is the table,
// not the presence of the component elsewhere in the scene.
TEST_CASE("group: an ungrouped draw is unaffected by another entity's group") {
    Harness h;
    h.list.setSortingGroup(51, {/*layer=*/0, /*order=*/100, false, 0});
    BatchVertex quad[4] = {};

    BatchDrawKey a = quadKey(1, /*layer=*/2);
    BatchDrawKey b = quadKey(2, /*layer=*/1);
    b.shaderId = 8;

    appendQuad(h.pool, h.list, h.clips, quad, a);
    appendQuad(h.pool, h.list, h.clips, quad, b);
    h.list.finalize(h.pool);

    REQUIRE(h.list.mergedDrawCallCount() == 2);
    CHECK(h.list.command(0).texture_ids[0] == 2);
    CHECK(h.list.command(1).texture_ids[0] == 1);
}

// A sprite cut to the inside of a mask and one cut to the outside of the SAME mask differ
// only in a state flag. Merged, one of them would be drawn with the other's stencil compare
// — the hole and the window are the same picture then.
TEST_CASE("stencil: inside and outside of one mask are different draws") {
    Harness h;
    h.clips.setStencilTest(61, 1);
    h.clips.setStencilTestOutside(62, 1);
    BatchVertex quad[4] = {};

    BatchDrawKey inside = quadKey(1, /*layer=*/2);
    inside.entity = Entity(61);
    BatchDrawKey outside = quadKey(1, /*layer=*/2);
    outside.entity = Entity(62);

    appendQuad(h.pool, h.list, h.clips, quad, inside);
    appendQuad(h.pool, h.list, h.clips, quad, outside);
    h.list.finalize(h.pool);

    REQUIRE(h.list.mergedDrawCallCount() == 2);
    CHECK((h.list.command(0).state_flags & CMD_STATE_STENCIL_OUT) == 0);
    CHECK((h.list.command(1).state_flags & CMD_STATE_STENCIL_OUT) != 0);
}

// Setting one mode must clear the other, or a sprite switched from outside to inside keeps
// both flags and reads as outside forever.
TEST_CASE("stencil: the two test modes are exclusive on one entity") {
    ClipState clips;
    clips.setStencilTestOutside(70, 3);
    clips.setStencilTest(70, 3);
    DrawCommand cmd{};
    clips.applyTo(Entity(70), cmd);
    CHECK((cmd.state_flags & CMD_STATE_STENCIL_TEST) != 0);
    CHECK((cmd.state_flags & CMD_STATE_STENCIL_OUT) == 0);

    clips.setStencilTestOutside(70, 3);
    DrawCommand back{};
    clips.applyTo(Entity(70), back);
    CHECK((back.state_flags & CMD_STATE_STENCIL_OUT) != 0);
}