added review

.review-gates/lenses/repo-better-solution.md

@@ -0,0 +1,67 @@
+## 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.