## This repository: Crafter.Graphics

The Crafter engine's graphics library: one C++ module, `Crafter.Graphics`,
one partition per file. On native targets it is a Vulkan 1.3+ renderer
built around `VK_EXT_descriptor_heap`, with a bindless descriptor-set
fallback, hardware ray tracing, a compute-shader UI and a Wayland or Win32
window; on `wasm32-*` the same C++ surface runs in a browser over WebGPU,
through the JS bridge in `additional/`. The stated design is `README.md`
(the manual), `AGENTS.template.md` (the contributor guide; `AGENTS.md` is
written from it and the dependencies' notes by every crafter-build run,
and is not in the tree), `AGENTS.consumer.md` (the notes consumers' agents
get) and the driver investigations in `examples/VulkanTriangle/README.md`
and `examples/Sponza/README.md`. The guide's "Design rules" are the
owner's decisions: a range that departs from one without saying so is a
finding; whether one should change is the owner's call, not a defect of
the range.

The layers: the partitions (`interfaces/`, `implementations/`), where the
target picks the backend in `project.cpp` and there is no runtime switch
and no abstraction layer: where the backends' APIs differ, the call site
`#ifdef`s. Every partition exists on every target, its body gated. The UI
kernels in `shaders/`, each compiled twice from one source, for the
descriptor heap and for the descriptor-set build (`.sets.spv`), which
`UIFallbackParity` holds pixel-identical, with their WGSL counterparts
baked into `additional/dom-webgpu.js`. `project.cpp`: the dependencies, the partition
and implementation lists, the shader builds and every test. The examples:
the in-tree consumers, GLSL and WGSL side by side. `UIDispatchHeader`
and the item structs are frozen and grow only through their reserved
`flags` bits and `_pad`, and `UIFusedHeader` is a separate contract, for
`DispatchFused`; a component is a stateless function over
buffers the user owns, never a hook or a virtual; the library enables only
the device features its own shaders use.

Search first: `Device::EnqueueDeletion` for a handle a frame in flight may
still use; `VulkanBuffer::Stage` for a staged re-upload;
`DescriptorHeapVulkan`'s slots (`AllocateBufferSlots`, `BufferSlot`,
`AddSwapchainSlot`); the barrier builders (`SwapchainStageUnion`,
`SwapchainWriterAccess`, `BuildSwapchainInterPassBarrier`,
`BuildTlasWriteBarrier`, `BuildTlasReadBarrier`) and `Device::stageMask`;
`ImageVulkan::Create` and `VulkanTransition`;
`Device::Initialize(required, optional)` for a feature an application's
shader needs; `UIRenderer`'s helpers, `Rect::SubRect` and `Inset`; the
decode helpers in `shaders/ui-shared.glsl`; the vendored `lib/` (stb,
libevdev, the generated Wayland protocol code); Crafter.Event,
Crafter.Math and Crafter.Asset as cloned under
`~/.cache/crafter.build/external/` or checked out beside this repository,
and the Vulkan headers and Vulkan-Utility-Libraries cloned there too.
What belongs in one of the three dependencies lands there first (the
commit guidelines), not as a local copy here. A driver workaround takes
the shape of the one there is: a `Device` flag, one fenced block, a kill
switch, a probe test and a status note.

Commit shape here, as the history shows and design rule 11 asks for the
examples and tests: a change travels in one commit with its test, the
examples and tests it breaks, and the README, `AGENTS.template.md` and
`AGENTS.consumer.md` text it makes untrue; a bug fix ships with a test
that fails before the fix (the testing instructions).

Compatibility: the consumers are the examples, each a `LocalProject` of
`../../project.cpp`, and the owner's applications, which pull `master`
unpinned and get `AGENTS.consumer.md` on their next build. Design rule 11
prefers the clean breaking change to a compatibility shim, so a break is
no finding by itself; a break the range does not carry through every
example, test and consumer-facing document in this tree is. The
environment switches `AGENTS.consumer.md` lists, the GLSL contract user
shaders `#include` from `ui-shared.glsl` and the shader file names
`ComputeShader::Load` resolves are contracts too.