Crafter.Graphics/interfaces/Crafter.Graphics-Device.cppm

//SPDX-License-Identifier: LGPL-3.0-only
//SPDX-FileCopyrightText: Copyright (C) 2026 Catcrafts®

module;
#ifndef CRAFTER_GRAPHICS_WINDOW_DOM
#include "vulkan/vulkan.h"
#endif
#ifdef CRAFTER_GRAPHICS_WINDOW_WAYLAND
#include <wayland-client.h>
#include <wayland-client-protocol.h>
#include "../lib/xdg-shell-client-protocol.h"
#include "../lib/wayland-xdg-decoration-unstable-v1-client-protocol.h"
#include "../lib/fractional-scale-v1.h"
#include "../lib/viewporter.h"
#include "../lib/text-input-unstable-v3-client-protocol.h"
#include <xkbcommon/xkbcommon.h>
#endif
export module Crafter.Graphics:Device;
import std;
import :Keys;         // KeyCode for keyboard repeat state

export namespace Crafter {
    struct Window;

    #ifdef CRAFTER_GRAPHICS_WINDOW_WAYLAND
    // Wayland's wl_keyboard.key only fires on real press/release — the
    // compositor expects the application to synthesize repeat events
    // itself using the rate/delay it advertises via wl_keyboard.repeat_info.
    struct KeyRepeatState {
        int rate  = 25;     // chars/sec
        int delay = 500;    // ms before first repeat
        bool active = false;
        KeyCode key = 0;
        std::string utf8;   // UTF-8 to re-emit as onTextInput, if any
        std::chrono::time_point<std::chrono::steady_clock> pressTime;
        std::chrono::time_point<std::chrono::steady_clock> lastFireTime;
        bool fired = false;  // a repeat has fired since the press: before it, lastFireTime is the press itself
    };
    // Repeats one tick may emit at once when frames stalled; the rest of the
    // stall is dropped, so a held key is never a burst of edits.
    inline constexpr int kKeyRepeatCatchUp = 3;
    #endif

    #ifndef CRAFTER_GRAPHICS_WINDOW_DOM
    // The core feature structs, one per Vulkan version: every feature promoted
    // to core is in exactly one of them, and Vulkan forbids naming a feature
    // through both its version's struct and the struct it was promoted from.
    // The features an application's own shaders and code use go to
    // Device::Initialize in these. Only the VkBool32 members are read, so sType
    // and pNext may be left zero, as `{.vulkan12 = {.shaderFloat16 = VK_TRUE}}`
    // leaves them. At namespace scope, like KeyRepeatState: a nested type with
    // member initializers can't be the type of an inline static inside Device.
    struct DeviceFeatures {
        VkPhysicalDeviceFeatures         vulkan10 {};
        VkPhysicalDeviceVulkan11Features vulkan11 { .sType = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_1_1_FEATURES };
        VkPhysicalDeviceVulkan12Features vulkan12 { .sType = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_1_2_FEATURES };
        VkPhysicalDeviceVulkan13Features vulkan13 { .sType = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_1_3_FEATURES };
        // Needs a Vulkan 1.4 GPU. Below 1.4 only maintenance5 can be on, which
        // the library enables through VK_KHR_maintenance5 there.
        VkPhysicalDeviceVulkan14Features vulkan14 { .sType = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_1_4_FEATURES };
    };
    // The features a GPU lacks, named the way an application writes them
    // ("vulkan12.shaderFloat16"), split by who needs them.
    struct FeatureGaps {
        std::vector<std::string> library;
        std::vector<std::string> application;
    };
    // One GPU as Device::ChooseDevice weighs it: no gaps means it can run the
    // application.
    struct DeviceChoice {
        VkPhysicalDeviceType type;
        std::string name;
        std::vector<std::string> gaps;
    };
    #endif

    struct Device {
        #ifndef CRAFTER_GRAPHICS_WINDOW_DOM
        // Creates the instance, picks a GPU and creates the device. `required`
        // and `optional` are what the application's own shaders and code use;
        // the library adds what it needs itself. A GPU without Vulkan 1.3, a
        // required extension, the library's needs or a required feature is
        // skipped (saying why, when it ranks above the one chosen); when none is
        // left this throws, naming each GPU's gaps. Optional features are enabled
        // where the chosen GPU has them: enabledFeatures says which.
        static void Initialize(const DeviceFeatures& required = {}, const DeviceFeatures& optional = {});
        #else
        static void Initialize();
        #endif

        #ifndef CRAFTER_GRAPHICS_WINDOW_DOM
        #ifdef CRAFTER_GRAPHICS_WINDOW_WAYLAND
        inline static wl_display* display = nullptr;
        inline static wl_seat* seat = nullptr;
        inline static xdg_wm_base* xdgWmBase = nullptr;
        // Optional protocols, like wpViewporter below: null on a compositor
        // that does not advertise them (GNOME has no xdg-decoration), and a
        // request on a null proxy crashes in libwayland, so check first.
        inline static wp_fractional_scale_manager_v1* fractionalScaleManager = nullptr;
        inline static zxdg_decoration_manager_v1* manager = nullptr;
        inline static xkb_keymap* xkb_keymap;
        inline static wl_compositor* compositor = nullptr;
        inline static Window* focusedWindow = nullptr;
        // The window with keyboard focus (wl_keyboard.enter/leave), apart from
        // the pointer's: a key arrives without the pointer ever having entered
        // (a touch phone, a key typed while the pointer hovers elsewhere), so the
        // keyboard handlers route by this and never by focusedWindow.
        inline static Window* keyboardWindow = nullptr;
        inline static wl_shm* shm = nullptr;
        inline static wp_viewporter* wpViewporter = nullptr;
        inline static xkb_context* xkb_context = xkb_context_new(XKB_CONTEXT_NO_FLAGS);
        inline static xkb_state* xkb_state;
        inline static std::vector<Window*> windows;
        inline static wl_pointer* wlPointer;
        inline static wl_pointer* seatPointer = nullptr;
        inline static wl_keyboard* seatKeyboard = nullptr;
        inline static wl_touch* wlTouch = nullptr;
        inline static Window* touchWindow = nullptr;   // the window under the fingers
        // The fingers down, by the compositor's id, in physical pixels. Plain
        // data: the statics here are constant-initialised on purpose.
        struct TouchSlot {
            std::int32_t id;
            float x;
            float y;
            bool used;
            Window* window;
        };
        inline static std::array<TouchSlot, 10> touchSlots{};
        static void ForgetTouches();
        // wl_data_device_manager + wl_data_device drive copy/paste. Bound
        // lazily in handle_global; the data device is created once both
        // the manager and the seat are present (registry binding order
        // isn't guaranteed). nullptr on compositors that don't expose
        // the manager — Clipboard::SetText silently no-ops there.
        inline static wl_data_device_manager* dataDeviceManager = nullptr;
        inline static wl_data_device* dataDevice = nullptr;
        // zwp_text_input_v3: one object per seat; the compositor says which
        // surface it follows (enter/leave), the events are state that done()
        // applies as a whole.
        inline static zwp_text_input_manager_v3* textInputManager = nullptr;
        inline static zwp_text_input_v3* textInput = nullptr;
        inline static Window* textInputWindow = nullptr;
        inline static std::uint32_t textInputDeleteBefore = 0;
        inline static std::uint32_t textInputDeleteAfter = 0;
        inline static bool textInputHasPreedit = false;
        inline static bool textInputHasCommit = false;
        inline static bool textInputHasDelete = false;
        // Sends the window's wanted text-input state when it has the focus.
        static void ApplyTextInput(Window* window);

        static void seat_handle_capabilities(void* data, wl_seat* seat, uint32_t capabilities);
        static void xdg_surface_handle_preferred_scale(void* data, wp_fractional_scale_v1*, std::uint32_t scale);
        static void xdg_wm_base_handle_ping(void* data, xdg_wm_base* xdg_wm_base, std::uint32_t serial);
        static void handle_global(void* data, wl_registry* registry, std::uint32_t name, const char* interface, std::uint32_t version);
        static void handle_global_remove(void* data, wl_registry* registry, uint32_t name);
        static void keyboard_keymap(void* data, wl_keyboard* keyboard, uint32_t format, int fd, uint32_t size);
        static void keyboard_enter(void *data, wl_keyboard *keyboard, uint32_t serial, wl_surface *surface, wl_array *keys);
        static void keyboard_leave(void *data, wl_keyboard *keyboard, uint32_t serial, wl_surface *surface);
        static void keyboard_key(void *data, wl_keyboard *keyboard, uint32_t serial, uint32_t time, uint32_t key, uint32_t state);
        static void keyboard_modifiers(void *data, wl_keyboard *keyboard, uint32_t serial, uint32_t mods_depressed, uint32_t mods_latched, uint32_t mods_locked, uint32_t group);
        static void keyboard_repeat_info(void *data, wl_keyboard *keyboard, int32_t rate, int32_t delay);
        static void pointer_handle_button(void* data, wl_pointer* pointer, std::uint32_t serial, std::uint32_t time, std::uint32_t button, std::uint32_t state);
        static void PointerListenerHandleMotion(void* data, wl_pointer* wl_pointer, std::uint32_t time, wl_fixed_t surface_x, wl_fixed_t surface_y);
        static void PointerListenerHandleAxis(void*, wl_pointer*, std::uint32_t time, std::uint32_t axis, wl_fixed_t value);
        static void PointerListenerHandleEnter(void* data, wl_pointer* wl_pointer, std::uint32_t serial, wl_surface* surface, wl_fixed_t surface_x, wl_fixed_t surface_y);
        static void PointerListenerHandleLeave(void*, wl_pointer*, std::uint32_t, wl_surface*);
        static void touch_down(void* data, wl_touch* touch, std::uint32_t serial, std::uint32_t time, wl_surface* surface, std::int32_t id, wl_fixed_t x, wl_fixed_t y);
        static void touch_up(void* data, wl_touch* touch, std::uint32_t serial, std::uint32_t time, std::int32_t id);
        static void touch_motion(void* data, wl_touch* touch, std::uint32_t time, std::int32_t id, wl_fixed_t x, wl_fixed_t y);
        static void touch_frame(void* data, wl_touch* touch);
        static void touch_cancel(void* data, wl_touch* touch);
        static void text_input_enter(void* data, zwp_text_input_v3* textInput, wl_surface* surface);
        static void text_input_leave(void* data, zwp_text_input_v3* textInput, wl_surface* surface);
        static void text_input_preedit(void* data, zwp_text_input_v3* textInput, const char* text, std::int32_t cursorBegin, std::int32_t cursorEnd);
        static void text_input_commit(void* data, zwp_text_input_v3* textInput, const char* text);
        static void text_input_delete(void* data, zwp_text_input_v3* textInput, std::uint32_t before, std::uint32_t after);
        static void text_input_done(void* data, zwp_text_input_v3* textInput, std::uint32_t serial);

        constexpr static wl_pointer_listener pointer_listener = {
            .enter = PointerListenerHandleEnter,
            .leave = PointerListenerHandleLeave,
            .motion = PointerListenerHandleMotion,
            .button = pointer_handle_button,
            .axis = PointerListenerHandleAxis,
        };
        constexpr static wl_touch_listener touch_listener = {
            .down = touch_down,
            .up = touch_up,
            .motion = touch_motion,
            .frame = touch_frame,
            .cancel = touch_cancel,
        };
        constexpr static zwp_text_input_v3_listener text_input_listener = {
            .enter = text_input_enter,
            .leave = text_input_leave,
            .preedit_string = text_input_preedit,
            .commit_string = text_input_commit,
            .delete_surrounding_text = text_input_delete,
            .done = text_input_done,
        };
        constexpr static wl_keyboard_listener keyboard_listener = {
            .keymap = keyboard_keymap,
            .enter = keyboard_enter,
            .leave = keyboard_leave,
            .key = keyboard_key,
            .modifiers = keyboard_modifiers,
            .repeat_info = keyboard_repeat_info,
        };
        constexpr static wl_seat_listener seat_listener = {
            .capabilities = seat_handle_capabilities,
        };
        constexpr static wl_registry_listener registry_listener = {
            .global = handle_global,
            .global_remove = handle_global_remove,
        };
        constexpr static xdg_wm_base_listener xdgWmBaseListener = {
            .ping = xdg_wm_base_handle_ping,
        };
        #endif

        inline static VkInstance instance = VK_NULL_HANDLE;
        inline static VkDebugUtilsMessengerEXT debugMessenger = VK_NULL_HANDLE;
        inline static VkPhysicalDevice physDevice = VK_NULL_HANDLE;
        inline static VkDevice device = VK_NULL_HANDLE;
        inline static std::uint32_t queueFamilyIndex = 0;
        inline static VkQueue queue = VK_NULL_HANDLE;
        inline static VkCommandPool commandPool = VK_NULL_HANDLE;
        inline static VkSwapchainKHR swapchain = VK_NULL_HANDLE;
        inline static PFN_vkGetAccelerationStructureBuildSizesKHR vkGetAccelerationStructureBuildSizesKHR;
        inline static PFN_vkCreateAccelerationStructureKHR vkCreateAccelerationStructureKHR;
        inline static PFN_vkDestroyAccelerationStructureKHR vkDestroyAccelerationStructureKHR;
        inline static PFN_vkCmdBuildAccelerationStructuresKHR vkCmdBuildAccelerationStructuresKHR;
        inline static PFN_vkGetAccelerationStructureDeviceAddressKHR vkGetAccelerationStructureDeviceAddressKHR;
        inline static PFN_vkCreateRayTracingPipelinesKHR vkCreateRayTracingPipelinesKHR;
        inline static PFN_vkGetRayTracingShaderGroupHandlesKHR vkGetRayTracingShaderGroupHandlesKHR;
        inline static PFN_vkCmdTraceRaysKHR vkCmdTraceRaysKHR;
        inline static PFN_vkCmdBindResourceHeapEXT vkCmdBindResourceHeapEXT;
        inline static PFN_vkCmdBindSamplerHeapEXT vkCmdBindSamplerHeapEXT;
        inline static PFN_vkWriteResourceDescriptorsEXT vkWriteResourceDescriptorsEXT;
        inline static PFN_vkWriteSamplerDescriptorsEXT vkWriteSamplerDescriptorsEXT;
        inline static PFN_vkCmdPushDataEXT vkCmdPushDataEXT;
        inline static PFN_vkGetPhysicalDeviceDescriptorSizeEXT vkGetPhysicalDeviceDescriptorSizeEXT;
        inline static PFN_vkGetDeviceFaultInfoEXT vkGetDeviceFaultInfoEXT;

        // VK_EXT_memory_decompression — opt-in. When the driver advertises it
        // and exposes the GDeflate 1.0 method, GPU asset decompression is
        // available; otherwise consumers fall back to CPU decode.
        inline static bool memoryDecompressionSupported = false;
        inline static PFN_vkCmdDecompressMemoryEXT vkCmdDecompressMemoryEXT = nullptr;

        inline static VkPhysicalDeviceMemoryProperties memoryProperties;

        // VkPhysicalDeviceLimits::nonCoherentAtomSize — the alignment (in bytes,
        // a power of two) that vkFlushMappedMemoryRanges / vkInvalidateMappedMemoryRanges
        // require for the offset and size of a sub-buffer range. Whole-buffer
        // (VK_WHOLE_SIZE) flushes sidestep it; ranged flushes must round outward
        // to it (see VulkanBuffer::FlushDevice(offset,bytes)). Populated at device
        // creation; defaults to 1 so the rounding math is well-defined before then.
        inline static VkDeviceSize nonCoherentAtomSize = 1;

        // Core physical-device properties, captured once at Initialize from the
        // VkPhysicalDeviceProperties2 query. Kept because the pipeline-cache
        // persistence path needs vendorID / deviceID / pipelineCacheUUID to
        // decide whether an on-disk blob was written by this exact device.
        inline static VkPhysicalDeviceProperties deviceProperties = {};

        // One process-wide pipeline cache fed to every vkCreate*Pipelines call
        // (compute UI/user shaders + RT pipelines). Pipeline compilation is a
        // one-time cold-start cost, not a per-frame one; a single shared cache
        // lets the driver reuse compiled shader binaries across the several
        // pipelines built at startup and — once persisted to disk (see
        // LoadPipelineCache / SavePipelineCache) — across runs. VK_NULL_HANDLE
        // until LoadPipelineCache runs; passing VK_NULL_HANDLE to a create call
        // is valid and simply means "no cache", so the create sites need no
        // null check.
        inline static VkPipelineCache pipelineCache = VK_NULL_HANDLE;
        // Where the serialized cache lives. Relative to the working directory,
        // matching the gpu_crash_dump-* convention. Set before Initialize to
        // relocate it.
        inline static std::filesystem::path pipelineCachePath = "pipeline_cache.bin";

        // ─── Optional capability groups ────────────────────────────────
        // Decided once by Initialize from the extensions the driver
        // advertises; false until then. Not every driver has the descriptor
        // heap (Mesa Turnip on Adreno has neither it nor ray tracing), so the
        // compute/UI path runs in one of two binding models:
        //   descriptorHeapSupported  -> VK_EXT_descriptor_heap, the *.spv shaders
        //   !descriptorHeapSupported -> one bindless descriptor set per frame
        //                               (DescriptorHeapVulkan sets mode), the
        //                               *.sets.spv shaders, vkCmdPushConstants
        // Setting the environment variable CRAFTER_GRAPHICS_NO_DESCRIPTOR_HEAP
        // forces the second model on any driver, for testing. In the same way
        // CRAFTER_GRAPHICS_NO_VULKAN_1_4 creates the instance as a Vulkan 1.3
        // application, so the 1.3 path (maintenance5 through
        // VK_KHR_maintenance5, no vulkan14 features) runs on a 1.4 GPU.
        inline static bool descriptorHeapSupported = false;
        // Ray tracing also needs the descriptor heap (RT pipelines and RT
        // shaders are heap-only), so this is never true without it.
        inline static bool rayTracingSupported = false;
        // VK_EXT_device_fault: the VK_ERROR_DEVICE_LOST report in CheckVkResult.
        inline static bool deviceFaultSupported = false;
        // VK_KHR_surface_maintenance1 (or its EXT form) with
        // VK_KHR_get_surface_capabilities2, instance extensions enabled where
        // the loader has them: a surface's capabilities for one present mode.
        // Its image counts can differ from the surface's answer for all modes,
        // and Window::CreateSwapchain asks for the mode it uses (#160).
        inline static bool surfaceMaintenance1Supported = false;
        inline static PFN_vkGetPhysicalDeviceSurfaceCapabilities2KHR vkGetPhysicalDeviceSurfaceCapabilities2KHR = nullptr;
        // VK_KHR_swapchain_maintenance1 (or its EXT form) with its
        // swapchainMaintenance1 feature, a device group enabled where the
        // driver has it. With it a swapchain is made naming its present mode
        // (VkSwapchainPresentModesCreateInfoKHR), which is what lets it have
        // that mode's image count where the surface's count for all modes is
        // higher (Turnip's FIFO: 3 where MAILBOX needs 4).
        inline static bool swapchainMaintenance1Supported = false;
        // Pipeline stages that are valid on this device: everything, minus
        // RAY_TRACING_SHADER when ray tracing is unsupported. AND it into any
        // stage mask built from a constant that names the RT stage.
        inline static VkPipelineStageFlags stageMask = ~VkPipelineStageFlags{0};
        // Throws std::runtime_error naming the missing capability when ray
        // tracing is unsupported. Called at every ray tracing entry point.
        static void RequireRayTracing();

        // ─── Device features ───────────────────────────────────────────
        // Every feature Initialize enabled: the library's own, the
        // application's required ones, and whichever optional ones the GPU has.
        // pNext is null. Read only the fields you asked for: the library's own
        // may change. All false before Initialize.
        inline static DeviceFeatures enabledFeatures {};
        // Every feature the chosen GPU supports, enabled or not. Below Vulkan
        // 1.4 vulkan14 holds maintenance5 alone, from VK_KHR_maintenance5.
        inline static DeviceFeatures supportedFeatures {};
        // The Vulkan version the application may use on the chosen GPU:
        // min(the instance's, the GPU's). Zero before Initialize.
        inline static std::uint32_t apiVersion = 0;
        // The GPU's subgroup size, stages and operations, which
        // CheckShaderCapabilities holds GroupNonUniform* capabilities to.
        inline static VkPhysicalDeviceVulkan11Properties vulkan11Properties = {
            .sType = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_1_1_PROPERTIES
        };
        // True when shaderInt64 is on only for the NVIDIA workaround's SPIR-V
        // rewrite (below): an application shader that declares Int64 still
        // needs the application to ask for it, or it would run only on NVIDIA.
        inline static bool shaderInt64ForWorkaroundOnly = false;
        // The features to enable on a GPU that supports `supported`: library ∪
        // required ∪ (optional ∩ supported), never one the GPU lacks. Each one
        // in `library` or `required` that it lacks goes to `gaps`. Below an
        // apiVersion of 1.4 a vulkan14 one is marked "(Vulkan 1.4 only)", but
        // maintenance5, which VK_KHR_maintenance5 provides there, is marked as
        // that extension's. Pure logic, driven by tests/DeviceFeatures without
        // a GPU.
        static DeviceFeatures ResolveFeatures(const DeviceFeatures& library, const DeviceFeatures& required,
                                              const DeviceFeatures& optional, const DeviceFeatures& supported,
                                              std::uint32_t apiVersion, FeatureGaps& gaps);
        // The GPU to use: the best device type among those without gaps
        // (discrete, integrated, virtual, other), a CPU device only when no
        // other kind is listed. Prints why each better-ranked GPU was passed
        // over, and throws listing every GPU's gaps when none qualifies. Pure
        // logic apart from that print, driven by tests/DeviceFeatures.
        static std::size_t ChooseDevice(std::span<const DeviceChoice> choices);
        // `instance`'s physical devices grouped by GPU, in the loader's order:
        // a GPU two drivers both list (a Flatpak sees the runtime's and the GL
        // extension's manifests; RADV beside AMDVLK) has one device UUID and
        // two handles. CRAFTER_GRAPHICS_DEVICE numbers these groups, so one
        // number means the same GPU inside a sandbox and out.
        static std::vector<std::vector<VkPhysicalDevice>> DistinctGpus(VkInstance instance);
        // Throws when `spirv` declares, directly or implicitly (Int64Atomics
        // declares Int64), a SPIR-V capability that nothing enabled: a core
        // feature that is off, a subgroup operation the GPU lacks, or one of
        // the library's optional groups (ray tracing, the descriptor heap) that
        // is off. Most drivers accept such a module silently. The message names
        // `file`, the capability, and either the field to pass to Initialize or
        // that the GPU lacks it. Capabilities a core version enables, and ones
        // no enabled extension can, are left to the driver and the validation
        // layer. VulkanShader calls it on every module, before the NVIDIA
        // rewrite. Reads enabledFeatures, supportedFeatures, apiVersion,
        // vulkan11Properties and the group flags, so tests can stage those.
        static void CheckShaderCapabilities(std::span<const std::uint32_t> spirv, const std::filesystem::path& file);

        // The two property structs below are only filled in (and only chained
        // into the properties query) when their capability group is supported;
        // otherwise they stay zero.
        inline static VkPhysicalDeviceDescriptorHeapPropertiesEXT descriptorHeapProperties = {
            .sType = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DESCRIPTOR_HEAP_PROPERTIES_EXT
        };
        inline static VkPhysicalDeviceRayTracingPipelinePropertiesKHR rayTracingProperties = {
            .sType = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_RAY_TRACING_PIPELINE_PROPERTIES_KHR
        };
        inline static VkPhysicalDeviceMemoryDecompressionPropertiesEXT memoryDecompressionProperties = {
            .sType = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MEMORY_DECOMPRESSION_PROPERTIES_EXT
        };
        inline static VkPhysicalDeviceDriverProperties driverProperties = {
            .sType = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DRIVER_PROPERTIES
        };

        // ─── NVIDIA descriptor-heap AS-read workaround (issue #15 / #7) ──
        // True only on the NVIDIA proprietary driver, where reading an
        // acceleration structure through VK_EXT_descriptor_heap aborts with
        // VK_ERROR_DEVICE_LOST (a brand-new-extension driver fault, verified
        // engine-clean in #7). When set, VulkanShader rewrites heap AS reads
        // into a TLAS-device-address + OpConvertUToAccelerationStructureKHR
        // path and RTPass pushes the active TLAS address as push data. Still
        // needed on 615.78.08. CRAFTER_GRAPHICS_NO_AS_WORKAROUND, set to any
        // value, turns it off to check a newer driver (tests/HeapASRead
        // --no-workaround). Delete this flag and everything keyed on it once a
        // fixed driver ships.
        inline static bool workaroundDescriptorHeapAS = false;

        // Count of ERROR-severity validation messages seen by the debug
        // messenger callback since instance creation. The callback only
        // prints (it never aborts), so tests that want to fail on a
        // validation error — e.g. a malformed acceleration-structure build —
        // assert this stays zero across the operation under test.
        inline static std::uint32_t validationErrorCount = 0;
        // The byte offset of the TLAS-address member inside a patched shader's
        // push-constant block is tracked per-shader (VulkanShader::tlasPushOffset),
        // not here: a single global is clobbered by whichever shader was patched
        // last and so cannot serve several shaders with differing push layouts
        // (e.g. an RT raygen and a ray-querying compute shader). RTPass and
        // ComputeShader read the offset off the pipeline they record.

        static void CheckVkResult(VkResult result);

        // ─── Pipeline cache persistence (issue #69) ─────────────────────
        // LoadPipelineCache creates `pipelineCache`, seeding it from
        // pipelineCachePath when the file exists *and* its header matches this
        // device (PipelineCacheDataCompatible) — a stale or foreign blob is
        // discarded so the driver never rejects it. Called once from
        // Initialize. SavePipelineCache writes the driver's current cache blob
        // back out; Initialize registers it with std::atexit so the cache is
        // serialized at process shutdown without any explicit teardown call.
        static void LoadPipelineCache();
        static void SavePipelineCache();
        // True when `data` is a VkPipelineCache blob whose header was written by
        // a device with the same vendorID / deviceID / pipelineCacheUUID as
        // `deviceProperties`. Pure logic over the standard 32-byte cache header,
        // so it is driven directly by the PipelineCacheValidation test with no
        // GPU device. A blob too short to hold the header is incompatible.
        static bool PipelineCacheDataCompatible(std::span<const std::byte> data);
        // Selects a memory type index from typeBits that satisfies `required`.
        // When `preferred` bits are also given, a type satisfying both is
        // chosen first; if none exists we fall back to required-only rather
        // than throwing. Throws only when even `required` cannot be met (no
        // valid memory exists for the allocation).
        static std::uint32_t GetMemoryType(std::uint32_t typeBits, VkMemoryPropertyFlags required, VkMemoryPropertyFlags preferred = 0);

        // Upload-strategy helper for a CPU-written, GPU-read buffer of `size`
        // bytes. Picks *where* the buffer should live, complementing
        // GetMemoryType (which picks the memory type once the strategy is set):
        //   true  -> allocate HOST_VISIBLE | DEVICE_LOCAL, map, write straight
        //            into device memory (no staging buffer, no copy).
        //   false -> allocate pure DEVICE_LOCAL and feed it from a HOST_VISIBLE
        //            staging buffer + vkCmdCopyBuffer.
        //
        // The decision is platform-dependent and made at runtime, never
        // hardcoded:
        //   1. No DEVICE_LOCAL | HOST_VISIBLE type exists (no resizable BAR) ->
        //      false: direct writes are impossible, staging is mandatory.
        //   2. ReBAR / UMA — the host-visible device-local heap is essentially
        //      the whole VRAM heap (>= 90% of the largest DEVICE_LOCAL heap) ->
        //      true: a staging copy would be pure overhead.
        //   3. Small BAR window — the host-visible device-local heap is a tiny
        //      window on a separate heap (<< VRAM) -> true only for buffers
        //      small enough to fit the window's per-buffer budget; large
        //      buffers stage so they don't exhaust the window (issue #58).
        //
        // This is the *upload* path (CPU-write -> GPU-read). Readback wants
        // HOST_CACHED instead (the ReBAR type is coherent-not-cached, so CPU
        // reads from it are slow) — keep that path separate. A more robust
        // small-window budget would consult VK_EXT_memory_budget for the
        // window's *remaining* space rather than its total size; that needs the
        // extension enabled and is a follow-up.
        //
        // Everything except the final size comparison depends only on
        // memoryProperties, so it is derived once by CacheUploadStrategy (called
        // at device creation) into the directWrite* members below; this leaves
        // the per-allocation call a single bounds check.
        static bool PreferDirectDeviceWrite(VkDeviceSize size);

        // Size-independent half of PreferDirectDeviceWrite, cached from
        // memoryProperties. directWriteBudget is the largest buffer that may be
        // written directly: 0 when no resizable BAR exists (always stage),
        // VkDeviceSize max for ReBAR/UMA (always map), or the small-window
        // per-buffer cap otherwise. Recompute via CacheUploadStrategy whenever
        // memoryProperties changes (device creation does this once).
        inline static VkDeviceSize directWriteBudget = 0;
        static void CacheUploadStrategy();

        // ─── Fence-keyed deferred resource deletion (issue #101) ────────
        // Since #40 dropped the per-frame vkQueueWaitIdle, frames are
        // pipelined: a buffer the CPU is "done" with may still be read by the
        // GPU for up to framesInFlight-1 more frames. Destroying it
        // immediately (as Clear() does) is then a use-after-free. Callers that
        // free a buffer which may still be in flight — VulkanBuffer::Resize's
        // reallocate path, VulkanBuffer::DeferredClear — hand the handles here
        // instead, tagged with the current frameCounter; ReclaimDeletions frees
        // an entry only once framesInFlight frames have elapsed, by which point
        // single-queue submission order guarantees all GPU work that could
        // reference it has completed. Destructors that own Vulkan handles
        // (VulkanBuffer, Mesh, VulkanShader, ComputeShader, PipelineRTVulkan)
        // queue them too: they can't know
        // whether a frame in flight still uses the handle, and a static owner
        // is destroyed after the driver and its layers have torn down, when no
        // Vulkan call may run. An entry holds one kind of handle; the others
        // stay VK_NULL_HANDLE.
        struct PendingDeletion {
            std::uint64_t retireAfter;   // frameCounter value at enqueue time
            VkBuffer buffer = VK_NULL_HANDLE;
            VkDeviceMemory memory = VK_NULL_HANDLE;
            VkAccelerationStructureKHR accelerationStructure = VK_NULL_HANDLE;
            VkShaderModule shaderModule = VK_NULL_HANDLE;
            VkPipeline pipeline = VK_NULL_HANDLE;
        };
        // Monotonic recorded-frame index, bumped once per Window::Render. Not
        // the same as Window::frameCounter (which is per-window and also drives
        // the acquire-semaphore slot) — this one is global so Mesh/Device code
        // can enqueue too, not just the window loop. Atomic: a destructor on
        // another thread reads it as it queues. It counts frames as one
        // window renders them: with several windows rendering, framesInFlight
        // of its counts pass sooner than each window's frames in flight, so
        // the deletion queue and the staging rings assume one window.
        inline static std::atomic<std::uint64_t> frameCounter = 0;
        // = Window::numFrames; set at window init. The number of frames that
        // must elapse after an enqueue before the resource is safe to free.
        // Zero until set, which only makes ReclaimDeletions more eager — and it
        // is never called before a Window (which sets this) starts rendering.
        inline static std::uint8_t framesInFlight = 0;
        // A deque, not a vector: frameCounter is monotonic, so retireAfter is
        // non-decreasing down the queue and the entries ready to reclaim are
        // always a prefix. ReclaimDeletions pops that prefix off the front in
        // O(ready) instead of walking and compacting the whole queue. Never
        // destroyed: static owners queue their handles from their destructors
        // at exit, and those may run after this queue's own destructor would.
        inline static std::deque<PendingDeletion>& deletionQueue = *new std::deque<PendingDeletion>();
        // Held by the calls below: handle owners go on whichever thread drops
        // them (a loader's, say) while the render loop reclaims. Never
        // destroyed, for the same reason as the queue.
        inline static std::mutex& deletionMutex = *new std::mutex();
        // Tag {buffer, memory} for deletion after framesInFlight more frames.
        // A VK_NULL_HANDLE buffer is ignored (nothing to free).
        static void EnqueueDeletion(VkBuffer buffer, VkDeviceMemory memory);
        // The same for an acceleration structure, a shader module and a
        // pipeline. Queue an acceleration structure before the buffer it lives
        // in: entries are freed in queue order. A VK_NULL_HANDLE is ignored.
        static void EnqueueDeletion(VkAccelerationStructureKHR accelerationStructure);
        static void EnqueueDeletion(VkShaderModule shaderModule);
        static void EnqueueDeletion(VkPipeline pipeline);
        // Free every entry whose retire frame has been reached
        // (retireAfter + framesInFlight <= frameCounter). Call once per frame
        // after waiting that frame's fence.
        static void ReclaimDeletions();
        // Free every queued entry unconditionally, and let every buffer's
        // staging ring start over. Call only after a wait-idle (resize /
        // teardown), when no in-flight GPU work can reference them. Without a
        // Window nothing else reclaims them: an app that has none calls this
        // after waiting for its work, or both only grow.
        static void DrainDeletions();
        // How many DrainDeletions have run: the staging rings start over
        // when it changes.
        inline static std::atomic<std::uint64_t> drains = 0;

        // ─── Wayland key repeat ────────────────────────────────────────
        // TickKeyRepeats fires onRawKeyDown / onRawKeyHold / onTextInput on
        // the focused window for whichever key is currently repeating.
        // Called once per frame from Window::Render. KeyRepeatState lives
        // at namespace scope so its member initializers don't trip C++'s
        // "complete-type-needed" rule for the inline static below.
        #ifdef CRAFTER_GRAPHICS_WINDOW_WAYLAND
        inline static KeyRepeatState keyRepeat;
        static void TickKeyRepeats();
        static void TickKeyRepeats(std::chrono::steady_clock::time_point now);   // the clock injected, for the tests
        #else
        static void TickKeyRepeats() {}
        #endif
        #else  // CRAFTER_GRAPHICS_WINDOW_DOM
        // DOM mode: Device collapses to just `Initialize()` (currently a
        // no-op since the JS runtime initializes itself). The function is
        // kept so user code calling `Device::Initialize()` still compiles
        // cross-platform. Browser key repeat is delivered through the
        // KeyboardEvent.repeat flag directly — no manual synthesis.
        static void TickKeyRepeats() {}

        // The frame clock, as on native: bumped at the end of every
        // Window::Render. The font atlas evicts by it (#55). One frame in
        // flight: a frame's queue.writeTexture runs before that frame's own
        // submit but after every earlier one, so only the frame being built
        // can still sample a texel the atlas writes.
        inline static std::atomic<std::uint64_t> frameCounter = 0;
        inline static std::uint8_t framesInFlight = 1;
        #endif
    };
}

#ifndef CRAFTER_GRAPHICS_WINDOW_DOM
// Not exported: shared by Device's implementation units.
namespace Crafter::DeviceDetail {
    // `parts` one after another, `separator` between them, for gap lists.
    std::string Join(std::span<const std::string> parts, std::string_view separator);
}
#endif