stoner-graphics-lab

Imported from WSSStone/stoner-graphics-lab (AGENTS.md). Install upstream with npx skills add WSSStone/stoner-graphics-lab. Copyright stays with the author.

Feature 026 Asset: Runtime Asset Manager is complete. GitHub Actions run 31882332020 passed all eight required Windows/macOS/Linux Debug and strict Release plus Linux ASan/UBSan/TSan jobs for revision 8427e13; artifact digests are recorded in Validation/026/CI/README.md. Read doc/026-runtime-asset-manager.html and specs/026-runtime-asset-manager/ for delivered design and evidence. Feature 027 Backend: Metal is the next roadmap target; create its Speckit feature from the Phase 027 prompt before implementation. Do not fold iOS lifecycle, Metal mesh shaders, ray tracing, or Asset ownership into 027. Feature 028 is now Asset: Production Content Integration & Acceptance; it uses licensed artist-authored content to validate source import through strict cooked loading and visible Vulkan/Metal rendering. Meshlet Derived Data and all former Features 028-038 were shifted to Features 029-039.

Active Technologies

• C++20 (traditional header/source separation; no C++20 Modules) + C++ standard library where portable (<chrono>, <filesystem>, <fstream>, <system_error>, <thread>); platform system libraries guarded behind Core implementation boundaries; SCons 4.10.1 build system (006-core-platform-abstraction)
• Local filesystem only for basic read/write/existence/directory operations; no persistent database or asset catalog (006-core-platform-abstraction)
• C++20 with traditional header/source separation + Existing Core layer types/math/logging/platform abstractions; SCons 4.10.1; C++ standard library for non-graphics utilities (007-rhi-core-interfaces)
• C++20 with traditional header/source separation + Existing Core layer types and containers; existing RHI core contracts (ERHIResult, ERHIFormat, ERHIQueueType, IRHIDevice, lifecycle/result conventions); SCons 4.10.1; C++ standard library for non-graphics utilities (008-rhi-resource-pipeline)
• C++20 with traditional header/source separation + Existing Core and RHI public contracts; Vulkan SDK or platform Vulkan loader/headers where available; platform presentation bridge guarded by backend implementation boundaries; SCons 4.10.1 (009-vulkan-backend-device)
• C++20 with traditional header/source separation + Existing Core types and RHI resource/descriptor contracts; existing Vulkan backend device, diagnostics, lifecycle, and SCons SDK detection; deterministic fallback allocation and process-local upload staging records; SCons 4.10.1 (010-vulkan-resource-management)
• C++20 with traditional header/source separation; no C++20 Modules + Existing Core types and containers; existing RHI command/queue/sync/resource/render pass/framebuffer contracts; existing Vulkan backend device, queue, sync, resource, diagnostics, and SCons SDK detection; Vulkan SDK or platform Vulkan loader/headers where available (011-vulkan-commands-submission)
• Process-local backend state only; command records, submission records, diagnostics, render pass/framebuffer objects, and upload scheduling records live in memory (011-vulkan-commands-submission)
• C++20 with traditional header/source separation; no C++20 Modules + Existing Core/RHI shader, descriptor, pipeline, command, render pass/framebuffer contracts; existing Vulkan backend device, resource, command, diagnostics, runtime fallback patterns, and SCons 4.10.1; Vulkan SDK or platform Vulkan loader/headers where available (012-vulkan-pipeline-shader)
• Process-local backend state only; shader modules, pipeline compatibility summaries, pipeline objects, command binding state, diagnostics, and pipeline reuse records live in memory; no persistent pipeline disk cache, database, or asset catalog (012-vulkan-pipeline-shader)
• C++20 with traditional header/source separation; no C++20 Modules + Existing Core types/containers/logging; existing RHI public contracts for resources, command buffers, barriers, queues, and result/lifecycle states; SCons 4.10.1 (013-render-graph-foundation)
• Process-local in-memory graph declarations, compiled schedules, diagnostics, transient resource records, imported resource bindings, and debug dump strings only (013-render-graph-foundation)
• C++20 with traditional header/source separation; no C++20 Modules + Existing Core types/containers/math/logging; existing Renderer render graph public contracts; existing RHI public shader/resource/descriptor/pipeline result conventions for compatibility checks; SCons 4.10.1 (014-material-shader-system)
• Process-local in-memory material definitions, material instances, parameter sets, shader records, shader permutations, resource reference identifiers, diagnostics, and inspection dump strings only (014-material-shader-system)
• C++20 with traditional header/source separation; no C++20 Modules + Existing Core types/containers/math/logging; existing Renderer render graph and material/shader public contracts; existing RHI public resource/result conventions only for abstract compatibility summaries; SCons 4.10.1 (015-forward-rendering-pipeline)
• Process-local in-memory forward frame inputs, prepared frame plans, view records, light records, mesh draw descriptions, render graph-compatible declaration summaries, diagnostics, and debug dump strings only (015-forward-rendering-pipeline)
• C++20 with traditional header/source separation; no C++20 Modules + Existing Core types/math/logging/platform abstractions; existing Renderer dependency boundary for future presentation handoff; SCons 4.10.1; GLFW-first real-window adapter behind Application implementation boundaries when available; deterministic headless/null window driver required for tests; GitHub Actions or equivalent Windows/macOS/Linux headless CI validation required for platform-sensitive coverage (016-window-input-system)
• Process-local in-memory window configuration, lifecycle state, event queues, input frame snapshots, loop state, diagnostics, and debug dump strings only; no persistent database, input recording, or preference storage (016-window-input-system)
• C++20 with traditional header/source separation; no C++20 Modules + Existing Core types, containers, math, strings, and logging/diagnostic conventions; existing Application window/input public boundary; existing Renderer forward/material public contracts only as abstract future handoff vocabulary; SCons 4.10.1 (017-scene-graph-ecs)
• Process-local in-memory world state, entity slot records, generation/version counters, component records, parent-child relationships, transform propagation caches, render collection summaries, diagnostics, and debug dump strings only; no persistent database, asset catalog, scene serialization, or live graphics resource ownership (017-scene-graph-ecs)
• C++20 with traditional header/source separation; no C++20 Modules + Existing Core, Application, Renderer, RHI, and Vulkan backend contracts; SCons 4.10.1; GLFW 3.4-compatible desktop window integration; Vulkan 1.3-compatible headers/loader; MoltenVK portability path on macOS; Mesa Lavapipe software Vulkan path on Linux CI; offline GLSL-to-SPIR-V compiler and SPIR-V validator when available (018-triangle-demo-integration)
• Repository-owned shader source and checked-in SPIR-V payloads; process-local runtime/frame/diagnostic state; local screenshot and log evidence under Validation/018/; no database or asset catalog (018-triangle-demo-integration)
• C++20 with traditional header/source separation; no C++20 Modules + Existing Core math/types/logging; Renderer material, forward, render-graph, and scene-identity contracts; RHI textures, buffers, descriptors, pipelines, render passes, command buffers, queues, fences, and runtime-mode contracts; existing Vulkan native offscreen context; SCons 4.10.1; Vulkan 1.3-compatible headers/loader; Mesa Lavapipe for Linux native CI; offline GLSL-to-SPIR-V compiler and validator when available (019-deferred-rendering-pipeline)
• Repository-owned deferred GLSL sources and checked-in SPIR-V payloads; process-local frame plans, surface layouts, graph declarations, RHI/native resources, readback probes, diagnostics, and comparison reports; CI report artifacts; no database, scene serialization, runtime shader cache, or asset catalog (019-deferred-rendering-pipeline)
• Process-local in-memory identities, metadata, dependency indexes, extension registrations, execution leases, diagnostics, and synthetic CPU payloads only; no persistent registry, database, manifest, cooked cache, or asset catalog (020-asset-core)
• C++20 with traditional header/source separation; no C++20 Modules + Existing Core types, containers, strings, logging, ownership, and platform conventions; new Core FUnicode NFC wrapper; C++ standard library concurrency and value facilities (<array>, <atomic>, <mutex>, <optional>, <shared_mutex>, <span>); Core-private vendored utf8proc 2.11.3 for Unicode 17 normalization; SCons 4.10.1 (020-asset-core)
• C++20, traditional public/private headers and sources; no Modules + Existing Core, Asset, RHI, Renderer; C++ standard library; pinned private stb_image 2.30; SCons 4.10.1 (021-image-texture-assets)
• Process-local immutable CPU image/texture payloads, mip chains, diagnostics, and checked-in fixtures; no database, manifest, cooked cache, or GPU handle in Asset (021-image-texture-assets)
• C++20 with traditional public/private headers and sources; C for private WAMR integration; no C++20 Modules + Existing Core, Asset, RHI, Renderer, Vulkan Backend; pinned private KTX-Software 4.4.2; pinned WAMR 2.4.5 interpreter; checked-in versioned encoder .wasm; SCons 4.10.1 (022-ktx2-cooking-compression)
• Immutable in-memory KTX2 bytes and request-scoped transcode payloads; checked-in fixtures and golden digests; no manifest, derived-data cache, package, database, or cross-request cache (022-ktx2-cooking-compression)
• C++20 with traditional public/private headers and sources; C for the private yyjson translation unit; no C++20 Modules + Existing Core and Asset contracts; Renderer/RHI/Application/Demo/Vulkan integration boundaries; pinned private yyjson 0.12.0; existing checked-in GLSL/SPIR-V; SCons 4.10.1 (023-material-shader-assets)
• Versioned canonical UTF-8 JSON authoring definitions plus separate repository-owned GLSL/SPIR-V dependency files under Content/; immutable in-memory Asset payloads and Renderer snapshots; no cooked binary, manifest, DDC, package, database, or runtime cache (023-material-shader-assets)
• C++20 with traditional public/private headers and sources; C99 for private cgltf and MikkTSpace translation units; no C++20 Modules + Existing Core, Asset, RHI, Renderer, Application, and Vulkan Backend contracts; pinned private cgltf v1.15 with accessor-overflow backport; pinned private MikkTSpace at 3e895b49d05ea07e4c2133156cfa94369e19e409; existing yyjson 0.12.0 and stb_image 2.30; SCons 4.10.1 (024-static-mesh-model)
• Source .gltf, .glb, external buffer, and image files resolved through IAssetResolver; immutable process-local CPU mesh/model payloads and Renderer RHI snapshots; checked-in fixtures and validation evidence; no database, manifest, DDC, package, or persistent runtime cache (024-static-mesh-model)
• C++20 with traditional public/private header and source separation; no C++20 Modules; Python 3 standard-library validation scripts + Existing Core and Asset contracts from Features 003-006 and 020-024; existing Asset-private yyjson 0.12.0 canonical JSON path; existing SHA-256 FAssetDigest; SCons 4.10.1; descriptor-owned POSIX flock/rename behind Core on macOS/Linux; durable Win32 file handles plus ReplaceFileW/MoveFileExW transaction primitives behind Core on Windows; no new third-party runtime dependency (025-asset-cooker-derived-data)
• Local source roots; local immutable directory-entry DDC; local self-contained cooked generation directories and atomic Current.json; checked-in target profiles, fixtures, schemas, and normalized validation evidence; shared Asset published-generation validation; no database, archive/package, remote cache, network service, or runtime cache (025-asset-cooker-derived-data)
• C++20 with traditional public/private headers and sources; no C++20 Modules; Python 3 standard-library validation scripts + Existing Core ownership, filesystem, Unicode, diagnostics, and platform lease contracts; Asset identity/metadata/extension dispatch from 020; immutable payload types and validators from 021-024; target profile, manifest, envelope codec, and published-generation validation from 025; C++ standard library concurrency (std::thread, std::mutex, std::condition_variable, atomics); SCons 4.10.1; no new third-party dependency (026-runtime-asset-manager)
• Immutable development source leases, one potentially read-only local published generation, and an explicit writable lease-coordination root; process-local request/operation/cache/diagnostic state; generation-scoped OS reader lease; no database, DDC ownership, package archive, persistent runtime cache, or network storage (026-runtime-asset-manager)

Recent Changes

• 006-core-platform-abstraction: Added C++20 (traditional header/source separation; no C++20 Modules) + C++ standard library where portable (<chrono>, <filesystem>, <fstream>, <system_error>, <thread>); platform system libraries guarded behind Core implementation boundaries; SCons 4.10.1 build system
• 007-rhi-core-interfaces: Planned RHI device, capabilities, command buffer, queue, synchronization, headless swapchain, result/status, and mock-test contracts
• 008-rhi-resource-pipeline: Planned RHI buffer, texture, sampler, shader module, descriptor, pipeline, render pass, framebuffer, lifecycle invalidation, and mock-test contracts
• 009-vulkan-backend-device: Implemented Vulkan backend runtime initialization, deterministic adapter selection, device/queue/sync objects, Core platform-window-backed surface validation, swapchain lifecycle, diagnostics, unsupported-runtime validation, and SCons SDK detection fallback
• 010-vulkan-resource-management: Implemented Vulkan backend buffers, textures, samplers, pipeline layouts, allocation ownership, deterministic fallback allocation, fixed-capacity descriptor pools, descriptor sets, upload staging records, diagnostics, lifecycle invalidation, and deterministic resource tests
• 011-vulkan-commands-submission: Implemented Vulkan command pools, command buffers, queue submission, deterministic fallback completion, minimal render pass/framebuffer scope, declarative barriers, upload scheduling, diagnostics, and regression tests
• 012-vulkan-pipeline-shader: Implemented Vulkan shader modules, explicit shader interface metadata, triangle-ready graphics pipelines, compute pipelines, process-local pipeline reuse, command binding validation, runtime/fallback diagnostics, lifecycle invalidation, documentation, and regression tests
• 013-render-graph-foundation: Implemented Renderer render graph declaration, deterministic compilation, virtual resource lifetime tracking, transition planning/execution, pass culling, transient resource resolution, aliasing eligibility diagnostics, text debug dumps, and mock RHI tests
• 014-material-shader-system: Implemented Renderer material definitions, instance inheritance with cycle detection, explicit in-memory precompiled shader records, per-shader permutation validation and variant binding, typed material parameters, abstract resource references, render graph resource requirements, deterministic diagnostics, text dumps, documentation, and regression tests
• 015-forward-rendering-pipeline: Implemented Renderer forward frame preparation, render graph-compatible pass/resource declarations, full PBR-style material input validation, configurable default-4 point light influence selection, transparent camera-space sorting, ambient-only fallback diagnostics, deterministic debug dumps, and headless regression tests
• 016-window-input-system: Planned Application primary window lifecycle, deterministic physical keyboard/mouse input state, resize/close/focus events, presentation-paused minimized/zero-drawable loop semantics, headless validation, optional real-window smoke validation, GitHub Actions/equivalent cross-platform CI validation, and public Application contracts
• 017-scene-graph-ecs: Implemented Application single-world scene graph and ECS foundation, generation-safe entity handles, single-instance transform/mesh/light/camera components, recursive hierarchy destruction, explicit component update/replace semantics, deterministic transform/subtree ordering, render collection ordering, diagnostics, documentation, and headless regression tests
• 018-triangle-demo-integration: Implemented a standalone StonerDemo composition root, explicit deterministic/native runtime modes, real Renderer forward-plan execution through backend-neutral native RHI bindings, two rotating Vulkan frame slots with image-indexed presentation synchronization, native offscreen Vulkan, GLFW surface/swapchain presentation, bounded endurance validation, formal Windows/macOS visible evidence, and passing three-platform CI with Linux Lavapipe native-headless validation
• 019-deferred-rendering-pipeline: Implemented a sibling deferred Renderer strategy with three color surface targets plus depth, normalized world-space normals, StandardZ/ReversedZ policies, directional/fullscreen and instanced point/spot volumes, render-graph/RHI execution, uncapped deterministic light handling, diagnostics, real mapped Vulkan attachment readback, runtime-independent and native failure injection, four-tier comparison artifacts, forward coexistence, and passing Windows/macOS/Linux CI with Linux Lavapipe evidence
• 020-asset-core: Implemented the Core-only Asset layer, NFC logical identity, SHA-256 version evidence, metadata/dependency registry with atomic batches and concurrent snapshots, deterministic resolver/importer dispatch, scoped extension registrations with execution leases, focused test-suite selection, architecture enforcement, diagnostics, inspection, and opt-in registry benchmark; Windows/macOS/Linux Debug and strict Release plus Linux ASan/UBSan passed in CI run 30347149237
• 023-material-shader-assets: Implemented versioned Material/Shader/Instance Assets, bounded canonical JSON, typed GLSL/SPIR-V dependencies, ordered target selection, complete source-version manifests, immutable Renderer snapshots, repository shader migration, bytecode-only native boundaries, deterministic corpus evidence, and passing Windows/macOS/Linux Debug and strict Release plus Linux ASan/UBSan/TSan validation in CI run 30553736883
• 024-static-mesh-model: Implemented bounded glTF/GLB static package import, Unreal-style coordinate normalization, typed immutable mesh/model payloads, stable multi-output identities, hierarchy, Material v2 and Image/Texture dependencies, transactional Renderer/RHI buffer realization, malformed corpus, deterministic/concurrent/performance gates, and passing Windows/macOS/Linux Debug and strict Release plus Linux ASan/UBSan/TSan and Lavapipe indexed readback in CI runs 31766671726 and 31766671729
• 025-asset-cooker-derived-data: Implemented deterministic target profiles, cook graph/input snapshots, typed payload envelopes, canonical manifests, local immutable DDC, incremental invalidation, native leases, long-path-safe atomic generation publication, standalone validation, normalized CLI reports, corruption/concurrency/performance gates, and passing Windows/macOS/Linux Debug and strict Release plus Linux ASan/UBSan/TSan in CI run 31827665459

Git Commit Style

• Commit messages must start with a conventional type prefix such as feat, docs, fix, chore, refactor, test, or build.
• Prefer type(scope): summary when a clear scope exists, for example docs(spec-006): align platform abstraction numbering.

Speckit Clarification Style

• During a Speckit Clarify workflow, state each question explicitly and completely before presenting the recommendation and answer options. The user must not have to infer the question from the recommendation or option table.