Stop workflow tool after validated version 2 report

.github/workflows/ci.yml

@@ -96,3 +96,4 @@ jobs:
           python-version: '3.12'
       - run: python -m pip install -r docs/requirements.txt
       - run: python -m mkdocs build --strict
+      - run: python tests/verify_playable_exports_test.py

.github/workflows/windows-graphics.yml

@@ -72,8 +72,8 @@ jobs:
         run: ctest --preset windows-debug --timeout 180
       - name: Real Release exports, 2D and 3D execution, incremental Debug rebuild
         run: build/windows-debug/faset_build_service_tests.exe --integration .cache/windows-export-e2e
-      - name: Export and relocate both checked-in playable games
-        run: python tools/verify_playable_exports.py --editor build/windows-debug/faset_editor.exe --output .cache/windows-playable-exports
+      - name: Export and relocate C++ and Lua playable games
+        run: python tools/verify_playable_exports.py --editor build/windows-debug/faset_editor.exe --output .cache/windows-playable-exports --include-lua
       - name: Preserve graphics and export evidence
         if: always()
         uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02

CMakeLists.txt

@@ -74,13 +74,16 @@ if(TARGET faset_assets AND TARGET faset_authoring AND EXISTS "${PROJECT_SOURCE_D
 endif()
 if(TARGET faset_editor_commands AND TARGET faset_build_service)
   include(cmake/Plugins.cmake)
-  add_library(faset_editor_session STATIC src/editor/session.cpp)
+  add_library(faset_editor_session STATIC src/editor/session.cpp src/editor/autosave.cpp)
   target_link_libraries(faset_editor_session PUBLIC faset_editor_commands faset_build_service faset_assets faset_editor_plugins)
   if(BUILD_TESTING)
     add_executable(faset_editor_session_tests tests/editor_session_tests.cpp)
     target_link_libraries(faset_editor_session_tests PRIVATE faset_editor_session)
     target_compile_definitions(faset_editor_session_tests PRIVATE FASET_TEST_ENGINE="${PROJECT_SOURCE_DIR}")
     add_test(NAME editor_session_settings COMMAND faset_editor_session_tests)
+    add_executable(faset_editor_autosave_tests tests/editor_autosave_tests.cpp)
+    target_link_libraries(faset_editor_autosave_tests PRIVATE faset_editor_session)
+    add_test(NAME editor_autosave COMMAND faset_editor_autosave_tests)
   endif()
 endif()
 foreach(module UI EditorUI Editor Applications)

PLAN.md

@@ -199,19 +199,7 @@ GPU instance record содержит стабильные slot/generation; пл
 
 ### P3. Освещение, тени и temporal reconstruction
 
-**Освещение, тени и измеренный выбор пути реализованы; приёмка всего P3 ещё
-открыта.** Есть authored directional/point/spot lights, общий shader ABI для
-Direct и P2, четыре каскада солнца, отдельный 16-face atlas для point/spot,
-видимость каскадеров из shadow views и общий бюджет 4096 caster draws.
-Ранжирование 128 local lights, атомарный отказ от шести point faces и
-unshadowed fallback доступны с диагностикой. На Linux reference GPU Release
-1920×1080 измеренный рост стоимости main raster превысил порог для проверки
-Forward+. Depth-free tiled путь 16×16 прошёл image parity, но полный build +
-raster на плотной контрольной сцене оказался медленнее; `Auto` оставлен на
-forward, явный tiled доступен для локализованных источников и выиграл в
-отдельном сценарии. [Исследование](docs/studies/23-p3-forward-plus-2026-09-24.md)
-и [протокол проверки](docs/validation/p3-lighting-2026-09-24/README.md)
-отделяют этот Linux checkpoint от финальной Windows/temporal приёмки.
+Расширить local lights, добавить clustered/Forward+ при измеренной необходимости, cascaded sun shadows и ограниченный local shadow atlas. Shadow views имеют собственную видимость и бюджеты.
 
 Затем: previous transforms, motion vectors, jitter, history rejection и TAA; temporal upscaling — после устойчивого TAA. Проверять тонкую геометрию, движение, disocclusion, camera cut и смену разрешения, сравнивать с режимом без temporal. У cache/pass видны затраты и причины обновления.
 

apps/editor_main.cpp

@@ -4,6 +4,7 @@
 #include <faset/editor/mcp.hpp>
 #include <faset/editor/session.hpp>
 #include <iostream>
+#include <memory>
 #include <thread>
 #ifdef FASET_HAS_EDITOR_UI
 #include <faset/editor/editor_ui.hpp>
@@ -40,7 +41,7 @@ void help() {
     std::cout
         << "Faset Editor\n"
            "  faset_editor                         Open the project launcher\n"
-           "  faset_editor --project PATH [--new NAME --dimension 2|3] [--scene RELATIVE_PATH]\n"
+           "  faset_editor --project PATH [--new NAME --dimension 2|3 [--language cpp|lua]] [--scene RELATIVE_PATH]\n"
            "  faset_editor --project PATH --mcp [--gui]\n"
            "  faset_editor --project PATH --command JSON [--wait]\n"
            "Options: --engine SDK_SOURCE, --headless, --frames N, --capture PATH.ppm\n"
@@ -52,9 +53,10 @@ int editor_main(int argc, char** argv) {
     using namespace faset::editor;
     try {
         std::filesystem::path project, engine = path_from_utf8(FASET_ENGINE_SOURCE), scene, capture;
-        std::string new_name, command;
+        std::string new_name, command, language = "cpp";
         int dimension = 3;
         bool mcp = false, gui = true, explicit_gui = false, wait = false;
+        bool explicit_language = false;
         std::uint64_t frames = 0;
         for (int i = 1; i < argc; ++i) {
             const std::string arg = argv[i];
@@ -74,6 +76,10 @@ int editor_main(int argc, char** argv) {
                 new_name = value();
             else if (arg == "--dimension")
                 dimension = std::stoi(value());
+            else if (arg == "--language") {
+                language = value();
+                explicit_language = true;
+            }
             else if (arg == "--scene")
                 scene = path_from_utf8(value());
             else if (arg == "--mcp")
@@ -100,30 +106,65 @@ int editor_main(int argc, char** argv) {
                 throw Error("cli.option", "Unknown option: " + arg);
         }
         require(!(mcp && !command.empty()), "cli.mode", "Choose MCP or a single command");
+        require(!explicit_language || !new_name.empty(), "cli.language",
+                "--language requires --new NAME");
+        require(language == "cpp" || language == "lua", "cli.language",
+                "Language must be cpp or lua");
         if (mcp && !explicit_gui)
             gui = false;
         require(!project.empty() || (gui && !mcp && new_name.empty()), "cli.project",
                 "Use --project PATH for command, MCP, or --new modes");
         auto previous_project = project;
+#ifdef FASET_HAS_EDITOR_UI
+        std::optional<ProjectSelection> retry_create;
+        std::string creation_error;
+#endif
         for (;;) {
             if (project.empty()) {
 #ifdef FASET_HAS_EDITOR_UI
                 const auto selection =
-                    run_project_launcher(engine, previous_project, frames, capture);
+                    run_project_launcher(engine, previous_project, frames, capture,
+                                         retry_create, creation_error);
+                retry_create.reset();
+                creation_error.clear();
                 if (!selection)
                     return 0;
                 project = selection->path;
                 new_name = selection->create ? selection->name : std::string();
                 dimension = selection->dimension;
+                language = selection->language;
+                explicit_language = selection->create;
 #else
                 throw Error("editor.gui_unavailable",
                             "This build has no graphical project launcher; use --project PATH");
 #endif
             }
-            Session session({std::filesystem::absolute(project), std::filesystem::absolute(engine),
-                             executable_directory(argv[0])});
-            if (!new_name.empty())
-                session.scaffold(new_name, dimension);
+            std::unique_ptr<Session> session_holder;
+            try {
+                session_holder = std::make_unique<Session>(SessionConfig{
+                    std::filesystem::absolute(project), std::filesystem::absolute(engine),
+                    executable_directory(argv[0])});
+                if (!new_name.empty()) {
+                    if (explicit_language)
+                        session_holder->scaffold(new_name, dimension, language);
+                    else
+                        session_holder->scaffold(new_name, dimension);
+                }
+            } catch (const std::exception& error) {
+#ifdef FASET_HAS_EDITOR_UI
+                if (gui && !new_name.empty()) {
+                    retry_create = ProjectSelection{std::filesystem::absolute(project),
+                                                    new_name, dimension, true, language};
+                    creation_error = error.what();
+                    project.clear();
+                    new_name.clear();
+                    scene.clear();
+                    continue;
+                }
+#endif
+                throw;
+            }
+            Session& session = *session_holder;
             const auto settings = session.project();
 #ifdef FASET_HAS_EDITOR_UI
             if (gui && std::filesystem::exists(project / "project.faset.json"))
@@ -167,6 +208,8 @@ int editor_main(int argc, char** argv) {
                 project.clear();
                 scene.clear();
                 new_name.clear();
+                explicit_language = false;
+                language = "cpp";
                 continue;
 #else
                 throw Error(

apps/player_main.cpp

@@ -48,7 +48,6 @@ struct ProfileSample {
     bool physicsDebug{};
     bool gpuVisibilityActive{};
     faset::render::VisibilityMode effectiveVisibilityMode{faset::render::VisibilityMode::Direct};
-    faset::render::FrameStats lighting;
 };
 Json distribution(std::vector<double> values) {
     if (values.empty())
@@ -97,43 +96,7 @@ Json profileFrames(const std::vector<ProfileSample>& samples) {
                           {"physics_debug", sample.physicsDebug},
                           {"gpu_visibility_active", sample.gpuVisibilityActive},
                           {"effective_visibility_mode",
-                           visibility_mode_name(sample.effectiveVisibilityMode)},
-                          {"effective_lighting_path", sample.lighting.effective_lighting_path},
-                          {"submitted_local_lights", sample.lighting.submitted_local_lights},
-                          {"omitted_local_lights", sample.lighting.omitted_local_lights},
-                          {"requested_sun_cascades", sample.lighting.requested_sun_cascades},
-                          {"effective_sun_cascades", sample.lighting.effective_sun_cascades},
-                          {"requested_local_shadow_faces",
-                           sample.lighting.requested_local_shadow_faces},
-                          {"local_shadow_faces", sample.lighting.local_shadow_faces},
-                          {"local_shadow_tiles", sample.lighting.local_shadow_tiles},
-                          {"dropped_shadow_faces", sample.lighting.dropped_shadow_faces},
-                          {"dropped_point_shadow_faces",
-                           sample.lighting.dropped_point_shadow_faces},
-                          {"shadow_atlas_full_drops", sample.lighting.shadow_atlas_full_drops},
-                          {"shadow_caster_budget_drops",
-                           sample.lighting.shadow_caster_budget_drops},
-                          {"shadow_unavailable_drops",
-                           sample.lighting.shadow_unavailable_drops},
-                          {"shadow_caster_draws", sample.lighting.shadow_caster_draws},
-                          {"sun_shadow_atlas_bytes",
-                           sample.lighting.sun_shadow_atlas_bytes},
-                          {"local_shadow_atlas_bytes",
-                           sample.lighting.local_shadow_atlas_bytes},
-                          {"gpu_main_raster_ms",
-                           gpuMeasured ? Json(sample.lighting.gpu_main_raster_ms) : Json(nullptr)},
-                          {"gpu_sun_shadow_ms",
-                           gpuMeasured ? Json(sample.lighting.gpu_sun_shadow_ms) : Json(nullptr)},
-                          {"gpu_local_shadow_ms",
-                           gpuMeasured ? Json(sample.lighting.gpu_local_shadow_ms) : Json(nullptr)},
-                          {"gpu_light_tiles_ms",
-                           gpuMeasured ? Json(sample.lighting.gpu_light_tiles_ms) : Json(nullptr)},
-                          {"light_tile_count", sample.lighting.light_tile_count},
-                          {"light_tile_counts_valid", sample.lighting.light_tile_counts_valid},
-                          {"light_tile_candidate_count", sample.lighting.light_tile_counts_valid
-                              ? Json(sample.lighting.light_tile_candidate_count) : Json(nullptr)},
-                          {"light_tile_overflow_count", sample.lighting.light_tile_counts_valid
-                              ? Json(sample.lighting.light_tile_overflow_count) : Json(nullptr)}});
+                           visibility_mode_name(sample.effectiveVisibilityMode)}});
     }
     return {{"samples", std::move(frames)},
             {"summary_ms",
@@ -624,8 +587,7 @@ int player_main(int argc, char** argv) {
                      milliseconds(renderStarted, frameFinished), measured.cpu_ms, measured.gpu_ms,
                      measured.readback_cpu_ms, runtimeStats, measured.draw_calls, measured.vertices,
                      measured.gpu_allocated_bytes, measured.texture_count, debugPhysics,
-                     measured.gpu_visibility_active, measured.effective_visibility_mode,
-                     measured});
+                     measured.gpu_visibility_active, measured.effective_visibility_mode});
             }
             ++frames;
         }
@@ -657,7 +619,6 @@ int player_main(int argc, char** argv) {
                  {"visibility_mode", visibilityName},
                  {"effective_visibility_mode",
                   visibility_mode_name(stats.effective_visibility_mode)},
-                 {"effective_lighting_path", stats.effective_lighting_path},
                  {"simulation_mode", "synthetic_fixed_timestep"},
                  {"fixed_delta_seconds", config.fixedDelta},
                  {"percentile_method", "nearest_rank_all_completed_frames_no_warmup_exclusion"},

apps/project_launcher.cpp

@@ -75,6 +75,22 @@ ProjectSelection open_project(const fs::path& path) {
         throw std::runtime_error("Project name or scene type is invalid.");
     return {path, std::move(name), dimension, false};
 }
+bool fresh_destination(const fs::path& path) {
+    if (!fs::exists(path))
+        return true;
+    if (!fs::is_directory(path) || fs::is_symlink(path))
+        return false;
+    for (const auto& entry : fs::directory_iterator(path)) {
+        if (entry.path().filename() != ".faset" || !entry.is_directory() ||
+            entry.is_symlink())
+            return false;
+        for (const auto& internal : fs::directory_iterator(entry.path()))
+            if (internal.path().filename() != "cache" || !internal.is_directory() ||
+                internal.is_symlink() || !fs::is_empty(internal.path()))
+                return false;
+    }
+    return true;
+}
 Json recent_records(const fs::path& file) {
     try {
         auto j = read_json(file);
@@ -124,9 +140,11 @@ struct ProjectLauncher::Impl {
     std::optional<ProjectSelection> selected;
     bool create = false, cancelled = false, browsing = false, browser_valid = false;
     int dimension = 3;
+    std::string language = "cpp";
     std::string error;
     Impl(render::Renderer& r, const fs::path& engine, const fs::path& initial,
-         const fs::path& recents)
+         const fs::path& recents, const std::optional<ProjectSelection>& retry,
+         std::string creation_error)
         : renderer(r), ui(engine / "assets/fonts/NotoSans.ttf"),
           recents_file(recents.empty() ? recent_path() : recents) {
         auto theme = ui::Theme::load(engine / "assets/ui/dark.json");
@@ -147,13 +165,22 @@ struct ProjectLauncher::Impl {
         ui.set_ime(
             [this](bool enabled) { renderer.set_text_input(enabled); },
             [this](ui::Rect r) { renderer.set_text_input_area(r.x, r.y, r.width, r.height); });
-        const auto start = initial.empty() ? user_home() / "FasetProjects/MyGame" : initial;
+        const auto start = retry ? retry->path
+                                 : initial.empty() ? user_home() / "FasetProjects/MyGame" : initial;
         ui.update_text("launcher-path", path_to_utf8(start));
-        create = initial.empty();
+        create = retry ? retry->create : initial.empty();
+        if (retry) {
+            ui.update_text("launcher-name", retry->name);
+            dimension = retry->dimension;
+            language = retry->language;
+            error = std::move(creation_error);
+        }
         ui.find("launcher-open")->on_click = [this](Widget&) { set_mode(false); };
         ui.find("launcher-create")->on_click = [this](Widget&) { set_mode(true); };
         ui.find("launcher-2d")->on_click = [this](Widget&) { dimension = 2; };
         ui.find("launcher-3d")->on_click = [this](Widget&) { dimension = 3; };
+        ui.find("launcher-cpp")->on_click = [this](Widget&) { language = "cpp"; };
+        ui.find("launcher-lua")->on_click = [this](Widget&) { language = "lua"; };
         ui.find("launcher-submit")->on_click = [this](Widget&) { submit(); };
         ui.find("launcher-cancel")->on_click = [this](Widget&) { cancelled = true; };
         ui.find("launcher-name")->on_preview = [this](Widget&) { error.clear(); };
@@ -209,14 +236,14 @@ struct ProjectLauncher::Impl {
                     throw std::runtime_error("Enter a project name.");
                 if (name.size() > 256 || name.find_first_of("\r\n\t") != std::string::npos)
                     throw std::runtime_error("Use a short project name on one line.");
-                if (fs::exists(path) && (!fs::is_directory(path) || !fs::is_empty(path)))
+                if (!fresh_destination(path))
                     throw std::runtime_error("Create requires a new or empty directory.");
                 auto parent = path.parent_path();
                 while (!parent.empty() && !fs::exists(parent))
                     parent = parent.parent_path();
                 if (parent.empty() || !fs::is_directory(parent))
                     throw std::runtime_error("Project parent directory is unavailable.");
-                selected = ProjectSelection{path, name, dimension, true};
+                selected = ProjectSelection{path, name, dimension, true, language};
             } else
                 selected = open_project(path);
             error.clear();
@@ -351,14 +378,24 @@ struct ProjectLauncher::Impl {
         ui.find("launcher-create")->selected = create;
         ui.find("launcher-2d")->selected = dimension == 2;
         ui.find("launcher-3d")->selected = dimension == 3;
+        ui.find("launcher-cpp")->selected = language == "cpp";
+        ui.find("launcher-lua")->selected = language == "lua";
         ui.find("launcher-2d")->appearance =
             dimension == 2 ? Appearance::Quiet : Appearance::Default;
         ui.find("launcher-3d")->appearance =
             dimension == 3 ? Appearance::Quiet : Appearance::Default;
+        ui.find("launcher-cpp")->appearance =
+            language == "cpp" ? Appearance::Quiet : Appearance::Default;
+        ui.find("launcher-lua")->appearance =
+            language == "lua" ? Appearance::Quiet : Appearance::Default;
+        ui.find("launcher-language-hint")->text =
+            language == "cpp" ? "Compiled gameplay. Add Lua later if you need quick reloads."
+                              : "Lua gameplay reloads during development without a C++ rebuild.";
         for (const auto* id : {"launcher-name-label", "launcher-name", "launcher-dimension-label",
                                "launcher-dimensions", "launcher-name-group",
                                "launcher-name-space", "launcher-path-space",
-                               "launcher-dimension-group"})
+                               "launcher-dimension-group", "launcher-language-group",
+                               "launcher-language-space"})
             ui.find(id)->visible = create;
         ui.find("launcher-heading")->text = create ? "Create project" : "Open project";
         ui.find("launcher-submit")->text = create ? "Create project" : "Open project";
@@ -424,8 +461,11 @@ struct ProjectLauncher::Impl {
     }
 };
 ProjectLauncher::ProjectLauncher(render::Renderer& r, const fs::path& engine,
-                                 const fs::path& initial, const fs::path& recents)
-    : impl_(std::make_unique<Impl>(r, engine, initial, recents)) {}
+                                 const fs::path& initial, const fs::path& recents,
+                                 const std::optional<ProjectSelection>& retry,
+                                 std::string creation_error)
+    : impl_(std::make_unique<Impl>(r, engine, initial, recents, retry,
+                                   std::move(creation_error))) {}
 ProjectLauncher::~ProjectLauncher() = default;
 void ProjectLauncher::frame(const std::vector<render::Event>& events) {
     impl_->frame(events);
@@ -445,9 +485,11 @@ bool ProjectLauncher::cancelled() const {
 std::optional<ProjectSelection> run_project_launcher(const fs::path& engine,
                                                      const fs::path& initial,
                                                      std::uint64_t max_frames,
-                                                     const fs::path& capture) {
+                                                     const fs::path& capture,
+                                                     const std::optional<ProjectSelection>& retry,
+                                                     std::string creation_error) {
     render::Renderer renderer({1100, 720, "Faset Engine — Projects", false, true});
-    ProjectLauncher launcher(renderer, engine, initial);
+    ProjectLauncher launcher(renderer, engine, initial, {}, retry, std::move(creation_error));
     std::uint64_t frames = 0;
     while (!renderer.should_close() && !launcher.cancelled() && !launcher.selection() &&
            (max_frames == 0 || frames < max_frames)) {

assets/ui/project-launcher-layout.json

@@ -41,6 +41,15 @@
                 {"id": "launcher-3d", "kind": "button", "text": "3D", "layout": {"width": 116}}
               ]}
             ]},
+            {"id": "launcher-language-space", "kind": "row", "layout": {"height": 18}},
+            {"id": "launcher-language-group", "kind": "column", "layout": {"gap": 6}, "children": [
+              {"id": "launcher-language-label", "kind": "label", "text": "Gameplay language", "layout": {"height": 24}},
+              {"id": "launcher-languages", "kind": "row", "layout": {"height": 42, "gap": 4}, "children": [
+                {"id": "launcher-cpp", "kind": "button", "text": "C++", "layout": {"width": 116}},
+                {"id": "launcher-lua", "kind": "button", "text": "Lua", "layout": {"width": 116}}
+              ]},
+              {"id": "launcher-language-hint", "kind": "label", "text": "Compiled gameplay. Add Lua later if you need quick reloads.", "font_size": 12, "layout": {"height": 30}}
+            ]},
             {"id": "launcher-hint", "kind": "label", "text": "Open a directory containing project.faset.json.", "font_size": 13, "layout": {"height": 36}},
             {"id": "launcher-actions-space", "kind": "row", "layout": {"height": 22}},
             {"id": "launcher-actions-rule", "kind": "row", "layout": {"height": 1}},

cmake/BuildService.cmake

@@ -1,8 +1,18 @@
-add_library(faset_build_service STATIC ${PROJECT_SOURCE_DIR}/src/editor/build_service.cpp)
+add_library(faset_build_service STATIC
+  ${PROJECT_SOURCE_DIR}/src/editor/build_service.cpp
+  ${PROJECT_SOURCE_DIR}/src/editor/build_cache.cpp
+  ${PROJECT_SOURCE_DIR}/src/editor/build_diagnostics.cpp)
 target_include_directories(faset_build_service PUBLIC ${PROJECT_SOURCE_DIR}/include)
 target_compile_features(faset_build_service PUBLIC cxx_std_20)
 target_link_libraries(faset_build_service PUBLIC faset_core faset_scripting_project PRIVATE faset_assets faset_authoring Threads::Threads)
 if(BUILD_TESTING)
+  add_executable(faset_build_diagnostics_tests ${PROJECT_SOURCE_DIR}/tests/build_diagnostics_tests.cpp)
+  target_link_libraries(faset_build_diagnostics_tests PRIVATE faset_build_service)
+  add_test(NAME build_diagnostics COMMAND faset_build_diagnostics_tests)
+  add_executable(faset_build_cache_tests ${PROJECT_SOURCE_DIR}/tests/build_cache_tests.cpp)
+  target_link_libraries(faset_build_cache_tests PRIVATE faset_build_service)
+  target_compile_definitions(faset_build_cache_tests PRIVATE FASET_ENGINE_SOURCE="${PROJECT_SOURCE_DIR}")
+  add_test(NAME build_cache COMMAND faset_build_cache_tests)
   add_executable(faset_build_service_tests ${PROJECT_SOURCE_DIR}/tests/build_service_tests.cpp)
   target_link_libraries(faset_build_service_tests PRIVATE faset_build_service faset_assets)
   target_compile_definitions(faset_build_service_tests PRIVATE FASET_ENGINE_SOURCE="${PROJECT_SOURCE_DIR}")
@@ -13,5 +23,12 @@ if(BUILD_TESTING)
   target_link_libraries(faset_build_schema_tests PRIVATE faset_build_service faset_authoring faset_editor_commands)
   add_dependencies(faset_build_schema_tests faset_build_schema_tool)
   add_test(NAME build_schema_publication COMMAND faset_build_schema_tests $<TARGET_FILE:faset_build_schema_tool> ${PROJECT_SOURCE_DIR})
-  set_tests_properties(build_schema_publication PROPERTIES TIMEOUT 60)
+  # This fixture performs many full cache invalidations and process launches.
+  # Windows runner startup and antivirus overhead exceed 60 seconds even when
+  # individual native fixture commands finish normally.
+  if(WIN32)
+    set_tests_properties(build_schema_publication PROPERTIES TIMEOUT 240)
+  else()
+    set_tests_properties(build_schema_publication PROPERTIES TIMEOUT 60)
+  endif()
 endif()

cmake/EditorUI.cmake

@@ -47,5 +47,8 @@ if(TARGET faset_ui AND TARGET faset_editor_session AND TARGET faset_scene_view)
         set_tests_properties(editor_ui_gizmos PROPERTIES LABELS "gpu")
         add_test(NAME editor_ui_authoring COMMAND faset_editor_ui_tests)
         set_tests_properties(editor_ui_authoring PROPERTIES LABELS "gpu")
+        add_executable(faset_editor_ui_latency ${PROJECT_SOURCE_DIR}/tests/editor_ui_latency.cpp)
+        target_link_libraries(faset_editor_ui_latency PRIVATE faset_editor_ui)
+        target_compile_definitions(faset_editor_ui_latency PRIVATE FASET_TEST_ENGINE="${PROJECT_SOURCE_DIR}")
     endif()
 endif()

cmake/Renderer.cmake

@@ -17,14 +17,6 @@ foreach(FASET_ENTRY vertexMain fragmentMain shadowMain)
     DEPENDS "${PROJECT_SOURCE_DIR}/shaders/baseline.slang" "${PROJECT_SOURCE_DIR}/tools/compile_shader.py" VERBATIM)
   list(APPEND FASET_SHADER_OUTPUTS "${FASET_SHADER_OUTPUT}" "${FASET_SHADER_DIRECTORY}/${FASET_ENTRY}.reflection.json")
 endforeach()
-set(FASET_SHADER_OUTPUT "${FASET_SHADER_DIRECTORY}/lightTileMain.spv")
-add_custom_command(OUTPUT "${FASET_SHADER_OUTPUT}" "${FASET_SHADER_DIRECTORY}/lightTileMain.reflection.json"
-  COMMAND "${Python3_EXECUTABLE}" "${PROJECT_SOURCE_DIR}/tools/compile_shader.py"
-          --compiler "${SLANGC_EXECUTABLE}" --source "${PROJECT_SOURCE_DIR}/shaders/light_tiles.slang"
-          --entry lightTileMain --output "${FASET_SHADER_DIRECTORY}"
-  BYPRODUCTS "${FASET_SHADER_DIRECTORY}/lightTileMain.slang-reflection.json"
-  DEPENDS "${PROJECT_SOURCE_DIR}/shaders/light_tiles.slang" "${PROJECT_SOURCE_DIR}/tools/compile_shader.py" VERBATIM)
-list(APPEND FASET_SHADER_OUTPUTS "${FASET_SHADER_OUTPUT}" "${FASET_SHADER_DIRECTORY}/lightTileMain.reflection.json")
 foreach(FASET_ENTRY gpuVertexMain gpuShadowMain gpuCullMain gpuHzbMain gpuPostCullMain)
   if(FASET_ENTRY STREQUAL "gpuVertexMain" OR FASET_ENTRY STREQUAL "gpuShadowMain")
     set(FASET_GPU_DEFINE FASET_GPU_GRAPHICS=1)
@@ -48,25 +40,13 @@ add_custom_command(OUTPUT "${FASET_SHADER_DIRECTORY}/compatibility.spv"
           -o "${FASET_SHADER_DIRECTORY}/compatibility.spv"
   DEPENDS "${PROJECT_SOURCE_DIR}/shaders/compatibility.hlsl" VERBATIM)
 add_custom_target(faset_shaders DEPENDS ${FASET_SHADER_OUTPUTS} "${FASET_SHADER_DIRECTORY}/compatibility.spv")
-add_library(faset_render "${PROJECT_SOURCE_DIR}/src/render/renderer.cpp" "${PROJECT_SOURCE_DIR}/src/render/math.cpp" "${PROJECT_SOURCE_DIR}/src/render/render_graph.cpp" "${PROJECT_SOURCE_DIR}/src/render/shader_contract.cpp" "${PROJECT_SOURCE_DIR}/src/render/lighting.cpp")
+add_library(faset_render "${PROJECT_SOURCE_DIR}/src/render/renderer.cpp" "${PROJECT_SOURCE_DIR}/src/render/math.cpp" "${PROJECT_SOURCE_DIR}/src/render/render_graph.cpp" "${PROJECT_SOURCE_DIR}/src/render/shader_contract.cpp")
 target_include_directories(faset_render PUBLIC "${PROJECT_SOURCE_DIR}/include")
 target_compile_features(faset_render PUBLIC cxx_std_20)
 target_link_libraries(faset_render PRIVATE Vulkan::Vulkan SDL3::SDL3 faset_core)
 target_compile_definitions(faset_render PRIVATE FASET_SHADER_DIRECTORY="${FASET_SHADER_DIRECTORY}")
 add_dependencies(faset_render faset_shaders)
 if(BUILD_TESTING)
-  add_executable(faset_render_lighting_gpu_tests "${PROJECT_SOURCE_DIR}/tests/render_lighting_gpu_tests.cpp")
-  target_link_libraries(faset_render_lighting_gpu_tests PRIVATE faset_render)
-  add_test(NAME render_lighting_sun COMMAND faset_render_lighting_gpu_tests --sun)
-  set_tests_properties(render_lighting_sun PROPERTIES LABELS "gpu;p3")
-  add_test(NAME render_lighting_local COMMAND faset_render_lighting_gpu_tests --local)
-  set_tests_properties(render_lighting_local PROPERTIES LABELS "gpu;p3")
-  add_test(NAME render_lighting_tiled COMMAND faset_render_lighting_gpu_tests --tiled)
-  set_tests_properties(render_lighting_tiled PROPERTIES LABELS "gpu;p3")
-  add_executable(faset_render_lighting_policy_tests "${PROJECT_SOURCE_DIR}/tests/render_lighting_policy_tests.cpp")
-  target_link_libraries(faset_render_lighting_policy_tests PRIVATE faset_render)
-  add_test(NAME render_lighting_policy COMMAND faset_render_lighting_policy_tests)
-  set_tests_properties(render_lighting_policy PROPERTIES LABELS "p3")
   add_executable(faset_render_tests "${PROJECT_SOURCE_DIR}/tests/render_tests.cpp")
   target_link_libraries(faset_render_tests PRIVATE faset_render SDL3::SDL3)
   add_test(NAME render_graph COMMAND faset_render_tests --unit)
@@ -98,17 +78,5 @@ if(BUILD_TESTING)
   target_link_libraries(faset_render_window_tests PRIVATE faset_render SDL3::SDL3)
   add_test(NAME render_window_lifecycle COMMAND faset_render_window_tests "${CMAKE_BINARY_DIR}/window-test")
   set_tests_properties(render_window_lifecycle PROPERTIES LABELS "gpu;window" TIMEOUT 40 SKIP_RETURN_CODE 77)
-  add_executable(faset_p3_lighting_benchmark
-    "${PROJECT_SOURCE_DIR}/examples/renderer/p3_lighting_benchmark.cpp")
-  target_link_libraries(faset_p3_lighting_benchmark PRIVATE faset_render faset_core)
-  target_compile_definitions(faset_p3_lighting_benchmark PRIVATE
-    FASET_BENCHMARK_CONFIGURATION="$<CONFIG>")
-  add_test(NAME render_lighting_benchmark_schema COMMAND
-    "${Python3_EXECUTABLE}" "${PROJECT_SOURCE_DIR}/tests/test_p3_lighting_benchmark.py")
-  set_tests_properties(render_lighting_benchmark_schema PROPERTIES LABELS "p3" TIMEOUT 90)
-  add_test(NAME render_lighting_benchmark_smoke COMMAND
-    "${Python3_EXECUTABLE}" "${PROJECT_SOURCE_DIR}/tests/test_p3_lighting_benchmark.py"
-    --real-executable "$<TARGET_FILE:faset_p3_lighting_benchmark>")
-  set_tests_properties(render_lighting_benchmark_smoke PROPERTIES LABELS "gpu;p3" TIMEOUT 90)
 endif()
 install(FILES ${FASET_SHADER_OUTPUTS} DESTINATION shaders)

docs/IMPLEMENTATION.md

@@ -466,66 +466,3 @@ rendered 120 frames in Direct mode. The corresponding
 [native/manual CI run](https://github.com/emil28092005/Faset_Engine/actions/runs/35922643004)
 passed on Linux and Windows. Unsupported-HZB integration and physical Windows
 GPU coverage remain untested.
-
-## P3 lighting checkpoint — authored lights and bounded shadow views
-
-At source revision `b191ae0`, the versioned `faset.light` schema and SceneView
-extract directional, point, and spot lights. Any authored Light, even disabled,
-suppresses the compatibility sun; scenes without a Light keep their previous
-appearance. The renderer validates all local records, then selects at most 128
-by priority, projected influence, and stable ID. A single typed lighting
-descriptor ABI serves Direct and P2 GPU graphics: materials remain set 0,
-lighting is set 1, GPU scene graphics data moves to set 2, and existing push
-constant sizes remain unchanged. Both paths shade the same sun/local PBR lights
-before tone mapping.
-
-A pure CPU shadow planner builds up to four texel-snapped sun cascades from an
-explicit camera frustum, ending at at most 80 world units; a low-level Snapshot
-without the frustum keeps one shadow view. Shadow caster bounds come from the
-source LOD-0 draw and are tested against the light view, independently of
-camera/P2 culling. The Vulkan backend renders the sun to its own D32 atlas and
-point/spot shadows to a separate 4×4 D32 atlas. A point light claims six faces
-atomically, a spot one. Both atlases try 2048² and then 1024² if required by
-capabilities or allocation. The combined frame budget is 4096 caster draws;
-scheduled tiles are cleared and redrawn each frame. Overflow, disabled shadow,
-or unavailable atlas leaves a submitted light illuminating without shadow.
-There is no hidden sun raster when the sun is absent, its shadow is disabled, or
-the scene only has sprites. Atlas ownership, dropout, submitted light counts,
-actual raster work and GPU timings are exposed in `FrameStats`, Player profiles
-and the optional Editor diagnostics overlay.
-
-The implementation's Linux Debug checkpoint at `a5fb216` built all targets and
-ran 60 CTests with no failures; the existing native window lifecycle test
-skipped under the compositor. The optional ImGui overlay passed its dedicated
-test in an enabled build. After benchmark integration at `b191ae0`, six focused
-tests passed, including the real Vulkan benchmark smoke. These are bounded
-checks, not a final P3 acceptance run. The [lighting validation record](validation/p3-lighting-2026-09-24/README.md)
-lists cases, exact revision, and remaining Windows/Release evidence.
-
-The fixed-scene Release reference-GPU sweep uses 1920×1080, 0/4/16/32/64/128
-lights, Direct/GPU frustum/GPU occlusion, shadows on/off, three independent
-repeats, ten warm-up and thirty measured frames per configuration. It reached
-the agreed Forward+ gate: main-raster overhead at 32 lights was about 0.50 ms
-relative to the matching zero-light case, roughly 30% of that GPU frame;
-64 and 128 lights added about 1.02 and 2.03 ms. Its raw CSV/report are being
-published separately with the exact benchmark revision and driver.
-
-Revision `a0a4e29` adds an explicit depth-free 16×16 tiled Forward+ path. One
-compute invocation tests every submitted point/spot range sphere against a
-tile's four screen-space planes and writes at most 64 stable-order indices.
-An overflowing tile scans the entire submitted list in the fragment shader;
-there is no dropped light. The tile shader has exact reflection validation,
-package/build integration, GPU timing, optional occupancy readback, and
-reload rollback. Direct, GPU frustum and GPU occlusion image tests cover a
-cropped viewport, resize, near-plane light/shadow, and overflow. A 128-light
-localized 1920×1080 forward/tiled capture matched byte for byte.
-
-The [paired Release study](studies/23-p3-forward-plus-2026-09-24.md) measured
-tile build **plus** raster on the same RTX 2080 Ti source revision and shader
-bundle. At 32/64/128 broad overlapping lights it was 0.064/0.122/0.222 ms
-slower; all 8160 tiles overflowed at 128. A separate localized-range scene
-was 0.103/0.214/0.440 ms faster at those counts, with no overflows. There is
-no robust scene/device runtime predictor yet, so `Auto` remains forward and
-`Tiled` is explicit. Linux Debug passed 62 CTests with one window skip;
-pinned Linux SwiftShader passed all six P3 cases. Windows CI on this new
-revision and P3 temporal reconstruction are separate acceptance work.

docs/manual/editor/diagnostics.md

@@ -1,5 +1,28 @@
 # Developer diagnostics
 
+## Build errors and source navigation
+
+Build and export jobs report compiler, clang-cl/MSVC, and Lua errors as structured
+Console rows. Each row shows severity, message, and a one-based source location.
+Choose **Open source** to open a file under the current project's `Scripts/`
+directory at that line and column. Diagnostics from engine or external files remain
+visible but have no source action. The **Jobs** tab shows whether a verified build
+generation was reused, the elapsed phases, and an expandable raw process log;
+**Copy full log** retains the complete available output for troubleshooting.
+
+The same action is available over Editor MCP:
+
+```json
+{"command":"faset_source_open","arguments":{"path":"Scripts/Gameplay.cpp","line":17,"column":4}}
+```
+
+`faset_script_open` remains Lua-only. Both commands use the project's optional
+`editor.script_editor` argv array, or Zed by default. The tokens `{file}`,
+`{line}`, `{column}`, and `{project}` may appear within one argument, for
+example `["zed", "{file}:{line}:{column}"]`. Faset passes each argument
+literally to the editor process without shell expansion. An invalid editor
+command produces a source-editor error without changing the build result.
+
 The optional Dear ImGui overlay shows renderer counters inside the Editor. The Editor's normal interface remains the retained Faset UI. Enable the diagnostic build explicitly:
 
 ```sh
@@ -16,33 +39,7 @@ The panel reports the previous completed frame: renderer wall time, GPU timestam
 
 In **GPU occlusion** mode, enable **Show HZB** to inspect the current grayscale depth pyramid. The **Mip** slider selects a pyramid level; the preview starts at mip 3 to keep its readback small. A larger mip number shows coarser depth. The preview reads the HZB only while the panel and toggle are open, and only once per completed frame or mip change. Switching it off or closing the panel releases the preview; its GPU texture retires when the next frame begins. Opening diagnostics also enables readback of GPU visibility counters, which is disabled again when the panel closes. Disable the HZB preview for performance comparisons: its diagnostic copy and texture upload add GPU and CPU work. **Freeze counters** does not freeze the HZB image.
 
-The **Lighting and shadows** section reports the actual local lights submitted
-and omitted, requested/effective sun cascades, requested/rasterized local faces,
-allocated local tiles, and shadow caster draws against the 4096-draw limit.
-Dropped-face counters distinguish a full atlas, caster budget, and unavailable
-atlas; `point` counts faces dropped as a complete six-face group. A light whose
-shadow faces are dropped still illuminates without a shadow. Atlas memory is the
-live explicit Vulkan allocation size for the separate sun and local atlases.
-When GPU timestamps are available, the panel shows sun and local shadow pass
-durations. A zero duration after a disabled sun or sprite-only frame confirms
-that no sun shadow raster ran. The lighting path names the algorithm actually
-used, so compare it with a benchmark's requested mode before interpreting costs.
-For an explicitly tiled frame, the overlay also reports the 16×16 grid size,
-its compute GPU duration, the number of stored light candidates, and how many
-tiles overflowed their 64-index list and scanned all lights. Candidate and
-overflow counts require the diagnostics readback; **unavailable** is distinct
-from a measured zero. The diagnostic copy itself adds work, so close the panel
-before measuring performance.
-See [Lighting](lighting.md) for the 128-light and 16-tile limits.
-
-The Vulkan backend emits `VK_EXT_debug_utils` labels for `SunShadowAtlas`,
-`LocalShadowAtlas`, `LightTileBuild` when tiled, `ForwardAndUI`, `Readback`, and, when presenting,
-`Presentation`. A fallback frame can have no shadow-raster label. A graphics
-capture tool that supports this extension can identify the command-buffer
-regions. Labels remain available without the Khronos validation layer when
-the extension is exposed; unsupported systems continue rendering and report
-labels unavailable. A submitted-label count confirms calls were emitted, not
-that an external capture tool was tested.
+The Vulkan backend emits `VK_EXT_debug_utils` labels for `ShadowMap`, `ForwardAndUI`, `Readback`, and, when presenting, `Presentation`. A graphics capture tool that supports this extension can identify those command-buffer regions. Labels remain available without the Khronos validation layer when the extension is exposed; unsupported systems continue rendering and report labels unavailable. A submitted-label count confirms calls were emitted, not that an external capture tool was tested.
 
 This module is disabled by default and is linked only to the graphical Editor and its dedicated test when enabled. Player and exported games do not link ImGui. No overlay control changes authoring documents, gameplay state or export settings.
 

docs/manual/editor/lighting.md

@@ -1,161 +0,0 @@
-# Light a 3D scene
-
-Select an entity in the **Scene** tree, choose **+ Add Component** in the
-**Inspector**, and add **Light**. Its Transform places a point or spot light. A
-spot light points along the entity's local negative Z axis; a directional light
-uses the entity's orientation. Lights affect 3D meshes in linear PBR shading
-before tone mapping. Sprites and Editor UI remain unlit.
-
-| Light kind | Coverage | Shadow cost |
-| --- | --- | --- |
-| `directional` | A sun-like direction, independent of position | Up to four cascade tiles |
-| `point` | All directions within `range` | Six local-atlas tiles, assigned together |
-| `spot` | A cone within `range` | One local-atlas tile |
-
-The Light component's fields are:
-
-| Field | Default | Meaning |
-| --- | --- | --- |
-| `kind` | `directional` | `directional`, `point`, or `spot` |
-| `enabled` | `true` | A disabled light contributes no illumination |
-| `color` | `[1, 1, 1, 1]` | RGB illumination color; alpha is part of the schema color value |
-| `intensity` | `1` | Nonnegative brightness |
-| `range` | `10` | Positive reach of point and spot lights |
-| `inner_angle` | `0.35` | Full-strength spot cone half-angle, in radians |
-| `outer_angle` | `0.7` | Outer spot cone half-angle, in radians; must be at least `inner_angle` |
-| `casts_shadow` | `true` | Allow this light to use its shadow atlas |
-| `shadow_priority` | `0` | Higher local-light selection and shadow priority; does not change brightness |
-
-The Inspector validates the spot angles together. Their allowed outer limit is
-below π/2 radians. A point light does not depend on the entity's rotation.
-After editing the light or Transform, save the scene as usual. [Editor
-workspace](workspace.md) explains Inspector editing, Undo, and save conflicts.
-
-## Sun shadows and compatibility
-
-With a 3D scene camera, a shadow-casting directional light uses four cascades
-covering the camera near plane through at most **80 world units**, or the camera
-far plane if it is closer. Faset blends samples near cascade splits and snaps
-each shadow projection to texels to reduce shimmer during small camera moves.
-Objects outside the camera view can still cast into a visible receiver: shadow
-visibility uses each light's view and the source mesh's LOD 0, separately from
-the main camera's Direct or GPU visibility result. A low-level renderer Snapshot
-without an explicit camera frustum uses one compatibility sun view.
-
-Only one enabled directional light is used. If there are several, Faset chooses
-the one with the smallest stable entity ID and reports the ignored lights. A
-scene with **no Light component** retains the older white sun. Adding any Light
-component, including a disabled one, suppresses that compatibility sun. Thus a
-local-only scene does not receive an unexpected directional light.
-
-## Local shadow capacity and fallbacks
-
-The renderer accepts at most **128** local lights per frame. It sorts candidates
-by `shadow_priority` (highest first), then projected influence, then stable ID.
-The `omitted_local_lights` counter reports lights beyond this limit; an omitted
-light contributes no illumination. All authored light records are validated,
-including candidates past the limit.
-
-The separate local shadow atlas has **16 tiles**. A spot consumes one; a point
-consumes six or none. Sun cascades and local shadows share a maximum of **4096
-caster draws** per frame. A light whose shadow group does not fit the remaining
-tiles or draw budget still illuminates, **without a shadow**. Disabling
-`casts_shadow` also keeps illumination while skipping that light's shadow work.
-The renderer reports requested faces, rendered faces, tiles, and drops by cause
-in [Diagnostics](diagnostics.md) and the [Player profile](profiling.md).
-
-Faset uses separate sampled D32 sun and local atlases, normally 2048×2048 pixels
-each. If a device cannot use that size, the renderer tries 1024×1024; if a
-sampled depth atlas cannot be created, the affected lights fall back to unshadowed
-illumination and report unavailable shadow views. Scheduled atlas tiles are
-cleared and redrawn each frame; there is no persistent shadow cache yet.
-Sprite-only scenes, a missing sun, and a sun with `casts_shadow: false` skip sun
-shadow raster work.
-
-## Local-light rendering path
-
-The normal `Auto` setting uses the measured forward light scan. It is the
-current default for Editor and Player. A C++ renderer integration can explicitly
-set `RendererConfig::lighting_mode = LightingMode::Tiled` to build depth-free
-16×16 screen-tile lists on a capable Vulkan device. Each tile stores at most
-64 light indices in stable order. If more lights touch a tile, its fragment
-shader scans the complete submitted list, so an overflow never removes
-illumination. The path falls back to forward when no local lights are present
-or the compute/buffer requirements are unavailable. Sprites and UI stay unlit.
-
-This explicit path can help when light ranges occupy small parts of the screen;
-it costs extra work when nearly every light covers nearly every tile. The
-fixed dense benchmark was slower after including tile construction, so there
-is no automatic scene-dependent switch yet. The Player profile reports
-`effective_lighting_path`, tile GPU time and grid size; optional Editor
-diagnostics also report stored candidates and overflowing tiles. See
-[Profiling](profiling.md) and the [measured Forward+ study](https://github.com/emil28092005/Faset_Engine/blob/main/docs/studies/23-p3-forward-plus-2026-09-24.md).
-
-## Add a point light through MCP
-
-MCP edits the **Editor document**, not entities in a running game. Use
-`faset_schema` to inspect the current field IDs, then send a `faset_scene_edit`
-batch with the document ID, its current revision, and a target entity ID:
-
-```json
-{
-  "document": "REPLACE_WITH_DOCUMENT_ID",
-  "revision": 4,
-  "idempotency_key": "add-red-point-light",
-  "operations": [{
-    "op": "component.add",
-    "entity": "REPLACE_WITH_ENTITY_ID",
-    "type": "faset.light",
-    "fields": {
-      "kind": "point",
-      "color": [1, 0.15, 0.1, 1],
-      "intensity": 8,
-      "range": 6,
-      "shadow_priority": 2
-    }
-  }]
-}
-```
-
-Move the entity with its Transform component. `component.add` fills omitted
-fields from the schema; `component.set` changes an existing field. Save the
-document with `faset_document_save`. [MCP and command line](mcp.md) covers
-revisions, retries, and transactions.
-
-## Supply lights directly from C++
-
-Code that constructs a renderer `faset::render::Snapshot` can supply lights
-directly. Set `authored_lights_present` even when the only authored Light is
-disabled, so the renderer does not synthesize the compatibility sun. Use stable,
-unique IDs for deterministic capacity decisions:
-
-```cpp
-faset::render::Snapshot snapshot;
-snapshot.authored_lights_present = true;
-
-faset::render::LocalLight point;
-point.kind = faset::render::LocalLight::Kind::Point;
-point.stable_id = "level/torch";
-point.position = {-2, 1.5f, 0};
-point.color = {1, 0.3f, 0.1f, 1};
-point.intensity = 8;
-point.range = 6;
-point.shadow_priority = 2;
-snapshot.local_lights.push_back(point);
-
-faset::render::LocalLight spot;
-spot.kind = faset::render::LocalLight::Kind::Spot;
-spot.stable_id = "level/lamp";
-spot.position = {2, 3, 0};
-spot.direction = {0, -1, 0};
-spot.inner_angle = 0.25f;
-spot.outer_angle = 0.55f;
-spot.intensity = 5;
-spot.range = 9;
-snapshot.local_lights.push_back(spot);
-```
-
-This is the **renderer Snapshot API**, not a gameplay `Update()` method. The
-current gameplay scripting API does not expose live Light-component creation or
-modification; author lights in the Inspector or through Editor MCP. See
-[Gameplay scripting](../scripting/index.md) for the APIs available to game code.

docs/manual/editor/mcp.md

@@ -67,6 +67,20 @@ resume and single-step process controls; it cannot read or modify game entities.
 scenes that have never been saved. Restoring an already open document requires its
 current revision. Recovery refuses to overwrite an externally changed scene file.
 
+Long-lived headless and graphical Editor sessions also poll the same autosave
+controller. With `editor.autosave` enabled (the default), a named dirty scene is
+saved after two seconds idle. `faset_autosave_status {}` reports `enabled` and each
+open document's `state`, `revision`, `path`, and `error`. States include `saved`,
+`pending`, `saving`, `conflict`, `failed`, `save_as_required`, and `disabled`.
+An unnamed scene remains in recovery until you give it an explicit path. An
+external disk edit produces `conflict` without overwriting that edit. For scripted
+workflows, use `faset_document_save` with `expected_revision` when you need a
+definite save boundary instead of waiting for idle autosave. If a conflict occurs,
+save to a new project-relative path and compare the two files. Change the
+preference through `faset_project_settings_get` and `faset_project_settings_set`
+with the returned project revision and `{"editor":{"autosave":false}}`; the
+new value applies to the current session and persists for the next Editor launch.
+
 ## Single-command CLI
 
 The CLI is useful for scripts that do not need an MCP session:

docs/manual/editor/profiling.md

@@ -118,80 +118,13 @@ and reads back the full image, so `cpu_ms` is wall time including waits, not CPU
 utilization. An open scene can run slower with HZB; visibility correctness and
 full-frame speed are separate findings.
 
-## Measure P3 lighting and shadows
-
-A Player `--profile` sample includes `effective_lighting_path`, local lights
-submitted/omitted, requested/effective sun cascades, requested/rasterized local
-shadow faces, tile use, shadow drop reasons, caster draws, and explicit atlas
-allocation bytes. `gpu_main_raster_ms`, `gpu_sun_shadow_ms`, and
-`gpu_local_shadow_ms` are GPU timestamps or `null` when timestamps are
-unavailable. A light can illuminate while its shadow faces are dropped. A
-submitted-light count of zero is a different workload from 128 lights whose
-shadows are disabled. See [Lighting](lighting.md) for the capacity policy and
-[Diagnostics](diagnostics.md) for the Editor counters.
-
-The same sample includes `effective_lighting_path` (`forward` or `tiled`),
-`gpu_light_tiles_ms`, and `light_tile_count`. Stored candidate and overflow
-counts are present only when visibility diagnostics readback was enabled;
-`light_tile_counts_valid: false` means their `null` values are unavailable,
-not zero. The normal `Auto` setting currently resolves to `forward` after the
-fixed dense 1080p benchmark showed that tile construction cost outweighed its
-raster savings. A C++ renderer integration can explicitly request `Tiled` for
-a localized-light scene, then check the actual path before comparing timings.
-
-The fixed-scene benchmark compares 0, 4, 16, 32, 64, and 128 local lights under
-Direct, GPU frustum, and GPU occlusion visibility, with shadows on and off. Its
-wrapper runs three independent 1920×1080 repetitions per configuration, each
-with ten warm-up and thirty recorded frames. First inspect the planned matrix:
-
-```sh
-python3 tools/benchmark_p3_lighting.py --list-runs
-```
-
-From the repository, after a Linux Release renderer build, run one shadow setting
-into a new output directory. Supply the actual device driver identity:
-
-```sh
-python3 tools/benchmark_p3_lighting.py --sweep \
-  --executable build/linux-release/faset_p3_lighting_benchmark \
-  --output .cache/p3-lighting-off \
-  --shadows off --driver 'REPLACE_WITH_ACTUAL_DRIVER' --validation off
-```
-
-The wrapper writes one raw CSV per run, `merged.csv`, and `summary.json`. Keep
-all three with the exact source revision and device. It checks that every run
-used its requested visibility mode and submitted every requested light. GPU
-timestamps for the main raster isolate fragment-heavy lighting better than
-renderer wall time, which includes GPU waits and synchronous readback. Shadow
-time is split into sun and local GPU durations. The Forward+ decision compares
-the median of three run medians against the matching zero-light configuration;
-the threshold is **1.0 ms extra main raster time or 15% of the zero-light GPU
-frame** at 32, 64, or 128 lights on the Linux physical reference GPU. The
-[P3 lighting validation record](https://github.com/emil28092005/Faset_Engine/blob/main/docs/validation/p3-lighting-2026-09-24/README.md)
-states the measured decision and scope. A software Vulkan run checks
-functionality, not physical GPU performance.
-
-For a direct comparison of the two algorithms on the same scene, invoke the
-Release executable twice with `--lighting forward` and `--lighting tiled`,
-using the same `--lights`, `--shadows`, `--visibility`, and output size. The
-default `--light-layout dense` preserves the fixed benchmark scene;
-`--light-layout localized` reduces point-light ranges to 1.75 units as a
-separately labelled workload. Compare `gpu_build_plus_raster_ms`, which includes
-`gpu_light_tiles_ms`, rather than raster time alone. One optional diagnostic
-frame with `--tile-diagnostics on` reports candidate and overflow counts but
-adds a GPU readback, so do not mix it into the timed runs. The
-[Forward+ measurement](https://github.com/emil28092005/Faset_Engine/blob/main/docs/studies/23-p3-forward-plus-2026-09-24.md) retains
-raw frames, shader hashes, and the decision.
-
 ## Current performance scope
 
 The accepted MVP path uses direct draws and CPU culling; P2 adds optional GPU
 visibility for opaque static meshes, with prepared LODs supplied by the project.
-P3 adds local lights and bounded sun/local shadow atlases. The benchmark's
-`lighting_path` and a Player profile's `effective_lighting_path` identify the
-algorithm actually used. Both paths currently use one graphics queue and
-synchronous full-image capture/readback. Use measurements to find the next
-bottleneck before introducing parallel jobs or expanding GPU-driven rendering.
-Neither an offscreen capture benchmark nor a tiny demo is a promise of a
-production frame budget. Observed measurements and follow-up targets belong in
-the implementation acceptance report with their source revision and method.
+Both paths currently use one graphics queue and synchronous full-image
+capture/readback. Use measurements to find the next bottleneck before introducing
+parallel jobs or expanding GPU-driven rendering. Neither an offscreen capture
+benchmark nor a tiny demo is a promise of a production frame budget. Observed
+measurements and follow-up targets belong in the implementation acceptance report
+with their source revision and method.

docs/manual/editor/workspace.md

@@ -50,6 +50,19 @@ outside the Editor, ordinary Save reports a conflict instead of overwriting it.
 Save your in-memory work to a new path and compare the two versions before replacing
 anything.
 
+Autosave is enabled by default. After a named scene has been idle for two seconds,
+the Editor saves its current revision to that scene file. The status bar shows
+**Pending autosave**, **Saving**, or **Saved**. An unnamed scene shows **Save As
+required** until you choose its path. The status bar's **Save As...** action opens
+an editable, new project-relative path; it never overwrites the conflicting file.
+
+If the disk file changes outside Faset, autosave stops for that revision and shows
+**Save conflict**. Use **Save As...** to keep both versions, then compare or reload
+the original. **Save failed** preserves the unsaved scene in the recovery journal;
+correct the write error or use Save As. Autosave does not clear Undo history or
+replace the [recovery journal](#recover-unsaved-work). Recovery still protects
+unnamed scenes and edits before the idle deadline.
+
 ## Navigate and transform
 
 - **Right drag:** orbit the 3D view; pan in a 2D scene.
@@ -119,13 +132,16 @@ for the C++ iteration loop.
 ## Project settings
 
 Open **File → Project settings** to change the project name, initial **2D / 3D** type,
-and start-scene path. Save a scene first, then choose it from the saved-scene list or
-enter its project-relative path. Choose **Save project** to update
-`project.faset.json` explicitly. A missing start scene is rejected and the dialog
-stays open.
+start-scene path, or **Autosave named scenes** preference. Save a scene first, then
+choose it from the saved-scene list or enter its project-relative path. Choose
+**Save project** to update `project.faset.json` explicitly. A missing start scene is
+rejected and the dialog stays open. The Autosave preference applies immediately;
+when disabled, the status bar says **Autosave off** and you can still use Ctrl+S or
+Save As. The project file stores it as `editor.autosave`; omitting it means enabled.
 
-These settings are used when the project opens again; they do not convert the active
-scene, switch its dimension, restart the Player, or add a scene Undo entry.
+The project name, default dimension, and start scene are used when the project opens
+again; they do not convert the active scene, switch its dimension, restart the Player,
+or add a scene Undo entry.
 **Cancel** or **Escape** discards this form's draft. If another writer changes the
 project settings while the dialog is open, Save reports a revision conflict and
 keeps your draft. **Reload saved** deliberately discards it and reloads the latest

docs/manual/getting-started/build.md

@@ -31,17 +31,27 @@ cmake --build --preset linux-debug --parallel
 ctest --preset linux-debug
 ```
 
-Create a project and open the native Editor:
+Create a runnable C++ or Lua starter and open the native Editor:
 
 ```sh
-build/linux-debug/faset_editor --project "$PWD/MyGame" --new MyGame --dimension 3
+build/linux-debug/faset_editor --project "$PWD/MyGame" --new MyGame --dimension 3 --language cpp
+build/linux-debug/faset_editor --project "$PWD/LuaGame" --new LuaGame --dimension 2 --language lua
 ```
 
 You can also run `build/linux-debug/faset_editor` without arguments to open the
-project launcher and create or select a project using the native interface.
+project launcher. Its Create view offers C++ 2D, C++ 3D, Lua 2D, and Lua 3D.
+Each explicit starter includes `Scenes/main.scene.json` with a player, ground,
+and a behavior bound to `Scripts/Gameplay.cpp` or `Scripts/main.lua`. 3D starters
+also include a camera and light. Existing files in a destination directory are
+never replaced by starter creation. The older `--new NAME --dimension 2|3`
+command without `--language` retains its original scene-free C++ scaffold.
 
 Use **Build** after changing `MyGame/Scripts/Gameplay.cpp`, then **Play**.
 The Player runs separately. Stop it before changing and rebuilding C++ gameplay.
+Lua starters declare their entry script in `project.faset.json`, install LuaLS
+annotations/configuration, and need no `Gameplay.cpp`. Use **Refresh Lua** after
+editing a Lua behavior declaration; development **Reload Lua** can apply a valid
+script edit to a running Player without recompiling C++.
 See [MCP and CLI](../editor/mcp.md) for headless authoring and automation.
 
 For an optimized build use `linux-release`. The `linux-sanitize` preset enables

docs/manual/scripting/lua.md

@@ -5,6 +5,23 @@ behaviors share the same runtime lifecycle, typed entity operations, scene compo
 and Inspector metadata. The Editor does not run gameplay code in its own process.
 There is no built-in script editor: edit `.lua` files in Zed or another external editor.
 
+## Start with a runnable Lua project
+
+Choose **Create project → Lua → 2D or 3D** in the native launcher, or run:
+
+```sh
+build/linux-debug/faset_editor --project "$PWD/LuaGame" --new LuaGame --dimension 2 --language lua
+```
+
+The starter creates `Scripts/main.lua`, a scene with a player and ground, and a
+manifest entry for that script. The player moves horizontally and jumps with the
+default input actions. The 3D choice also provides a camera and directional light.
+Open `Scripts/main.lua` in your external editor and change `speed` or
+`fixed_update`. **Refresh Lua** updates declared Inspector fields; **Reload Lua**
+updates a development Player after a valid edit without rebuilding native gameplay.
+The starter installs LuaLS declarations and `.luarc.json`; reopening it in Zed or
+another LuaLS-enabled editor provides completions for the Faset API.
+
 ## Enable Lua in a project
 
 Add explicit entry scripts to `project.faset.json`:

docs/studies/23-p3-forward-plus-2026-09-24.md

@@ -1,105 +0,0 @@
-# P3 Forward+ experiment: correctness and cost on localized lights
-
-The fixed 1920×1080 P3 benchmark crossed the agreed threshold for trying
-Forward+. A depth-free 16×16 tiled implementation now exists, but the measured
-**build + raster** cost is higher than a full light scan on that benchmark's
-dense lights. `RendererConfig::lighting_mode = Auto` therefore keeps the forward
-path. `Tiled` is an explicit option for scenes whose projected light volumes
-are localized. There is no unmeasured automatic occupancy heuristic.
-
-This is a follow-up to the fixed-scene baseline sweep, which is being merged
-as a separate study. It compares both paths in the same source revision
-`a0a4e29d480ed3344f19bd3565d48668ca913fed`. The baseline's dense
-placement remains the default. An explicit `--light-layout localized` changes
-only point-light range from 8 to 1.75 world units; camera, nine casters,
-receiver, positions, colors, light count, and output size are unchanged. The
-localized fixture is a separate workload, not a replacement for the fixed
-baseline gate.
-
-## Renderer behavior and safety
-
-The compute pass builds up to 64 stable-order light indices per screen tile.
-It tests each world-space range sphere against four clip-space tile planes.
-It does not use depth or reject near-plane intersections. A tile with more than
-64 candidates sets an overflow bit; the fragment shader then scans **all**
-submitted lights for that tile. Zero lights, missing capability, excessive
-buffer size, failed optional allocation, and `Auto` use the forward path. The
-shader contract checks the new compute entry's descriptors and 96-byte push
-constants; Direct and P2 GPU graphics still use materials at set 0, lighting
-at set 1, and GPU scene data at set 2. The tile list is set 1 binding 4 in the
-shared fragment shader. Sprite/UI shading returns before tile reads.
-
-The Linux Vulkan image test compares forward and tiled output in Direct, GPU
-frustum, and GPU occlusion modes, including a cropped scene viewport, near-plane
-crossing point light and shadow, resize, an offscreen light, and 80 coincident
-lights that exceed tile capacity. Every overflowing tile falls back to the full
-list. Shader reload preserves a working tiled pipeline after invalid bytecode
-and recreates it after a valid reload. A separate 1920×1080 capture with 128
-localized lights was byte-identical across both paths; its SHA-256 is in the
-[provenance record](data/p3-forward-plus-provenance-2026-09-24.json).
-
-## Measurement
-
-The device was NVIDIA GeForce RTX 2080 Ti with NVIDIA driver 595.84.0.0,
-Linux Clang Release, Direct visibility, shadows off, 1920×1080. Each mode had
-three independent process runs with ten warm-up and thirty measured frames.
-Forward/tiled run order alternated. The table uses the median of the three
-per-run medians in milliseconds. The tile build column is an actual GPU
-timestamp; `build + raster` also includes post raster if present. The dense
-and localized CSVs contain every one of the 1080 measured frames, with a
-`source_csv` identifier. The executable and all loaded `.spv`/reflection
-SHA-256 values are in the provenance record.
-
-| Light layout | Lights | Forward raster | Tile build | Tiled raster | Tiled build + raster | Tiled change |
-| --- | ---: | ---: | ---: | ---: | ---: | ---: |
-| Dense fixed scene | 32 | 0.5500 | 0.0617 | 0.5527 | 0.6144 | +0.0644 ms (11.7% slower) |
-| Dense fixed scene | 64 | 1.0701 | 0.1177 | 1.0740 | 1.1921 | +0.1220 ms (11.4% slower) |
-| Dense fixed scene | 128 | 2.1172 | 0.2219 | 2.1164 | 2.3388 | +0.2216 ms (10.5% slower) |
-| Localized range 1.75 | 32 | 0.2336 | 0.0555 | 0.0758 | 0.1312 | −0.1025 ms (43.9% faster) |
-| Localized range 1.75 | 64 | 0.4254 | 0.1060 | 0.1057 | 0.2109 | −0.2144 ms (50.4% faster) |
-| Localized range 1.75 | 128 | 0.8094 | 0.2048 | 0.1643 | 0.3691 | −0.4404 ms (54.4% faster) |
-
-At 32 dense lights, the first forward process had a 0.7405 ms run median;
-the other two were 0.5488 and 0.5500 ms. A single paired run would have
-incorrectly suggested a tiled win. The median of three process medians and a
-separate earlier repeat both support the slower dense result. This is why
-`Auto` remains forward despite the localized-scene gain. The total GPU frame
-also includes visibility, shadow fallback, copies, and synchronous readback;
-the table isolates the passes that the optimization changes. For example, at
-32 localized lights the full GPU frame was 1.6494 ms forward and 1.6472 ms
-tiled, essentially unchanged despite lower build + raster cost. At 128 it
-was 2.2788 versus 1.7948 ms.
-
-One diagnostic frame per layout/count copied the tile buffer after the timed
-draw. That copy was **not enabled** in the 1080 performance frames. The grid
-has 8160 tiles and a 64-index capacity per tile.
-
-| Layout | Lights | Stored candidates across tiles | Overflowed tiles |
-| --- | ---: | ---: | ---: |
-| Dense | 32 | 259,896 | 0 |
-| Dense | 64 | 519,792 | 0 |
-| Dense | 128 | 522,240 | 8,160 |
-| Localized | 32 | 38,237 | 0 |
-| Localized | 64 | 76,103 | 0 |
-| Localized | 128 | 152,202 | 0 |
-
-The dense 128 candidate count is capped at 64 × 8160 stored slots; all tiles
-overflow and correctly evaluate all 128 lights in the fragment shader. This
-explains why paying for tile construction cannot help that frame. The localized
-128 scene averages about 19 stored candidates per tile and avoids fallback.
-
-Raw data: [all paired frames](data/p3-forward-plus-ab-2026-09-24.csv),
-[diagnostic frames](data/p3-forward-plus-diagnostics-2026-09-24.csv), and
-[binary/shader provenance](data/p3-forward-plus-provenance-2026-09-24.json).
-
-## Verification and scope
-
-At the implementation revision, Linux Debug built all targets and passed
-62/63 CTests, with the compositor-dependent window lifecycle case skipped and
-no failures. The pinned Linux SwiftShader ICD passed all six P3 cases, including
-the tiled parity/overflow test. The [lighting validation record](../validation/p3-lighting-2026-09-24/README.md)
-retains those logs. These are functional checks on Linux and software Vulkan,
-not physical Windows GPU performance. The A/B numbers apply to one GPU, driver,
-camera, receiver and two synthetic light layouts. They do not establish an
-engine-wide speedup. A measured runtime occupancy predictor and representative
-game scenes are prerequisites before changing `Auto` from forward.

docs/studies/README.md

@@ -1,6 +1,6 @@
 # Исследования для Faset Engine
 
-Обновлено 24.09.2026. Исходники и официальная документация исследовались прежде всего 17.09.2026; затем результаты согласованы с принятой архитектурой. P2/P3 implementation/acceptance добавлены позже и отделены от исходного статического исследования.
+Обновлено 23.09.2026. Исходники и официальная документация исследовались прежде всего 17.09.2026; затем результаты согласованы с принятой архитектурой. P2 implementation/acceptance добавлены позже и отделены от исходного статического исследования.
 
 **Актуальные решения — в [ARCHITECTURE.md](../ARCHITECTURE.md), порядок реализации — в [PLAN.md](../../PLAN.md).** Реализация MVP и проверки идут отдельно: [журнал реализации](../IMPLEMENTATION.md), [результаты проверок](../validation/README.md), [пользовательский Manual](../manual/index.md). Исследования дают обоснования и проверочные сценарии; их статический анализ не является измерением Faset.
 
@@ -41,7 +41,6 @@ Linux/Windows, десктопные 2D/3D, C++ сначала и Lua следу
 - [19 — P2 GPU visibility: протокол приёмки](19-p2-gpu-visibility-acceptance.md): GPU-сценарии, допуски сравнения и методика измерений; отделяет проверку реализации от предложений исследования 15.
 - [20 — P2 GPU visibility: первый benchmark](20-p2-gpu-visibility-benchmark-2026-09-23.md): три запуска, raw CSV, p50/p95 и границы интерпретации на Linux reference GPU.
 - [21 — P2 GPU visibility: оптимизация MainCull](21-p2-gpu-visibility-optimization-2026-09-23.md): отдельные измерения переноса выходных буферов в память GPU и замены CAS-цикла на atomic add.
-- [23 — P3 Forward+: корректность и стоимость](23-p3-forward-plus-2026-09-24.md): сравнение полной цены построения плиток и рисования на плотной и локализованной сценах, raw CSV и точный shader/binary provenance.
 
 ## Происхождение и воспроизводимость
 

docs/studies/data/p3-forward-plus-diagnostics-2026-09-24.csv

@@ -1,7 +0,0 @@
-light_count,light_layout,shadows,visibility,effective_visibility,lighting_path,requested_lighting,build_configuration,run_index,frame,device,driver,commit,width,height,validation_enabled,validation_errors,submitted_local_lights,omitted_local_lights,requested_local_shadow_faces,rendered_local_shadow_faces,dropped_shadow_faces,shadow_atlas_full_drops,shadow_tiles,draw_calls,gpu_bytes,gpu_main_raster_ms,gpu_post_raster_ms,gpu_post_visible,visibility_counters_valid,gpu_sun_shadow_ms,gpu_local_shadow_ms,gpu_shadow_ms,gpu_light_tiles_ms,gpu_build_plus_raster_ms,light_tile_count,light_tile_counts_valid,light_tile_candidate_count,light_tile_overflow_count,gpu_ms,cpu_ms,readback_cpu_ms
-32,dense,off,direct,direct,tiled,tiled,Release,0,0,NVIDIA GeForce RTX 2080 Ti,NVIDIA 595.84.0.0,a0a4e29d480ed3344f19bd3565d48668ca913fed,1920,1080,0,0,32,0,0,0,0,0,0,10,63881248,0.551200,0.000000,0,0,0.000000,0.000000,0.000000,0.061472,0.612672,8160,1,259896,0,3.324384,4.920211,1.106698
-64,dense,off,direct,direct,tiled,tiled,Release,0,0,NVIDIA GeForce RTX 2080 Ti,NVIDIA 595.84.0.0,a0a4e29d480ed3344f19bd3565d48668ca913fed,1920,1080,0,0,64,0,0,0,0,0,0,10,63883808,1.077376,0.000000,0,0,0.000000,0.000000,0.000000,0.117440,1.194816,8160,1,519792,0,3.713568,5.236988,1.014093
-128,dense,off,direct,direct,tiled,tiled,Release,0,0,NVIDIA GeForce RTX 2080 Ti,NVIDIA 595.84.0.0,a0a4e29d480ed3344f19bd3565d48668ca913fed,1920,1080,0,0,128,0,0,0,0,0,0,10,63888928,2.109440,0.000000,0,0,0.000000,0.000000,0.000000,0.221184,2.330624,8160,1,522240,8160,4.435136,6.211166,0.970080
-32,localized,off,direct,direct,tiled,tiled,Release,0,0,NVIDIA GeForce RTX 2080 Ti,NVIDIA 595.84.0.0,a0a4e29d480ed3344f19bd3565d48668ca913fed,1920,1080,0,0,32,0,0,0,0,0,0,10,63881248,0.075328,0.000000,0,0,0.000000,0.000000,0.000000,0.055296,0.130624,8160,1,38237,0,2.355808,3.586245,0.930515
-64,localized,off,direct,direct,tiled,tiled,Release,0,0,NVIDIA GeForce RTX 2080 Ti,NVIDIA 595.84.0.0,a0a4e29d480ed3344f19bd3565d48668ca913fed,1920,1080,0,0,64,0,0,0,0,0,0,10,63883808,0.105248,0.000000,0,0,0.000000,0.000000,0.000000,0.105312,0.210560,8160,1,76103,0,2.445600,3.884127,1.069417
-128,localized,off,direct,direct,tiled,tiled,Release,0,0,NVIDIA GeForce RTX 2080 Ti,NVIDIA 595.84.0.0,a0a4e29d480ed3344f19bd3565d48668ca913fed,1920,1080,0,0,128,0,0,0,0,0,0,10,63888928,0.215040,0.000000,0,0,0.000000,0.000000,0.000000,0.229376,0.444416,8160,1,152202,0,2.585504,4.059668,0.951374

docs/studies/data/p3-forward-plus-provenance-2026-09-24.json

@@ -1,33 +0,0 @@
-{
-  "commit": "a0a4e29d480ed3344f19bd3565d48668ca913fed",
-  "device": "NVIDIA GeForce RTX 2080 Ti",
-  "driver": "NVIDIA 595.84.0.0",
-  "build": "Linux Clang Release",
-  "executable_sha256": "db151a07eeaee04871920f8617f5bcf4c8ac7cb11abf4e36e5595cc526440a36",
-  "shader_bundle_sha256": "60d2abf2f43557f72f39de7a50f4bc92816eb7859c613b2797c0410e72dbaeed",
-  "shader_bundle_hash_method": "SHA256 of UTF-8 canonical JSON mapping sorted shader filenames to per-file SHA256",
-  "shader_files": {
-    "vertexMain.spv": "1ad2631c35d654f48166321ae43d4165043e1b919b14f1dc61caf97b1ada0898",
-    "vertexMain.reflection.json": "b3bdff863d53a0b385e06a36701a83a6ecafe9a93e97281a732cce8ff862c0db",
-    "fragmentMain.spv": "eb65edf62a4ead573f740903dbbd1a61565fe97d234fbe8a09934ce6415bec92",
-    "fragmentMain.reflection.json": "6b62a42ea448d9ae253d78b6b326dfe0d761532ce695b49263689ec649ede36c",
-    "shadowMain.spv": "7643b4d688492b5ee923b9606f0b0e70343ca05fa67673838206119a6f86d8d8",
-    "shadowMain.reflection.json": "d39e2f83c797589296eac9dce139b9ad836a895d6685bc40f79dd2609d687fee",
-    "lightTileMain.spv": "92850edcc5ee5b586a90ce84ee69a98075a6fff3c13db4a57528d9431afe8b68",
-    "lightTileMain.reflection.json": "bf6a9256aaa6d6edacfa1e1c265d7c8ce2c1e4ea4036e0bea078c22fd4b536ca",
-    "gpuVertexMain.spv": "fc9770f304976875f8dd1f6acbe380c77cb06c13276f5596554b3f0b396b31bd",
-    "gpuVertexMain.reflection.json": "09166d80fba7ab4167e97f85125a7c58ab92ea447c1a6a2ab5084e657401dae9",
-    "gpuShadowMain.spv": "2da7e7f96bc7de4e9c8ac365fe0a63f608c7bb26ab3e7bfebfcf88b32e86c71d",
-    "gpuShadowMain.reflection.json": "c9dd844aefb3840f29caad5dfc53986cacc2220f886eda5ad345ebdbb9ff5b1c",
-    "gpuCullMain.spv": "7691360ec55f41d40d43652f506b051cef8b3a3ddcdcc7db61a7d4d97f9e87d8",
-    "gpuCullMain.reflection.json": "996fe5c7e31c6b8f316d8f290b3be0ae7063eb46c500a661e8715e9b822a2598",
-    "gpuHzbMain.spv": "08682362ee2120ed19d260e613285071747c3e436bb09bb6238e46f9cedc2308",
-    "gpuHzbMain.reflection.json": "589818f670881c64f3aba726ee3bc82fe4b9d835a347f99134e0e157dc4a112e",
-    "gpuPostCullMain.spv": "62cb72e356346e1511c6d640a3cecb4a6e5283795338299b357edae5f7f52be4",
-    "gpuPostCullMain.reflection.json": "eed140bbe09c7d14935b688c770261ac0e81677c0974aa811c88ed67ea779b95"
-  },
-  "matrix": "Direct, shadows off, 1920x1080, dense or localized, 32/64/128 lights, 3 repeats, 10 warmup + 30 measured frames; alternating A/B order",
-  "raw_rows": 1080,
-  "localized_128_capture_sha256": "2aa5d408867f7193b7fd83984f2333b188623bda4d083512ede6b8318f11b45c",
-  "localized_128_capture_exact_equal": true
-}

docs/superpowers/plans/2026-09-24-p3-lighting.md

@@ -42,9 +42,9 @@ Tasks 1–3 define the shared interfaces. Integrate Task 2's descriptor ABI befo
 
 **Files:** Modify `include/faset/render/renderer.hpp`, `src/authoring/schema.cpp`, `src/player/SceneView.cpp`, `tests/authoring_tests.cpp`, `tests/runtime_player_tests.cpp`, and relevant Manual authoring examples.
 
-**Interfaces:** Introduce `SunLight { stable_id, direction, color, intensity, casts_shadow }`, `LocalLight { Kind::Point|Spot, stable_id, position, direction, color, intensity, range, inner_angle, outer_angle, casts_shadow, shadow_priority }`, and `CameraFrustum { view, projection, near_plane, far_plane, perspective }`. Add `std::optional<SunLight> Snapshot::sun`, `std::vector<LocalLight> Snapshot::local_lights`, `bool Snapshot::authored_lights_present` (default false), and `std::optional<CameraFrustum> Snapshot::camera_frustum` after existing aggregate fields; retain `Snapshot::light_direction`. `SceneView::build` fills camera data for 3D scenes, sets authored-light presence even for disabled/future-version light components, and picks the first enabled directional by stable ID. A legacy sun is synthesized only when both sun and authored-light presence are absent.
+**Interfaces:** Introduce `SunLight { stable_id, direction, color, intensity, casts_shadow }`, `LocalLight { Kind::Point|Spot, stable_id, position, direction, color, intensity, range, inner_angle, outer_angle, casts_shadow, shadow_priority }`, and `CameraFrustum { view, projection, near_plane, far_plane, perspective }`. Add `std::optional<SunLight> Snapshot::sun`, `std::vector<LocalLight> Snapshot::local_lights`, and `std::optional<CameraFrustum> Snapshot::camera_frustum` after existing aggregate fields; retain `Snapshot::light_direction`. `SceneView::build` fills camera data for 3D scenes and picks the first enabled directional by stable ID.
 
-- [ ] **Step 1: Write failing schema/extraction tests.** Construct a version-1 scene with directional, point, and spot entities in one order and reversed order. Assert all local IDs/properties agree; authored sun color/intensity are preserved; a no-light scene has `authored_lights_present == false` and retains the default legacy sun, while a local-only or explicitly disabled-sun scene has the flag true and no sun. Extra directionals emit a diagnostic; invalid `range <= 0`, `inner_angle > outer_angle`, nonfinite color/transform, and unknown kind identify the entity/field. An essential assertion is:
+- [ ] **Step 1: Write failing schema/extraction tests.** Construct a version-1 scene with directional, point, and spot entities in one order and reversed order. Assert all local IDs/properties agree; authored sun color/intensity are preserved; no-light scene retains the default legacy sun; extra directionals emit a diagnostic; invalid `range <= 0`, `inner_angle > outer_angle`, nonfinite color/transform, and unknown kind identify the entity/field. An essential assertion is:
   ```cpp
   auto a = view.build(scene_with_three_lights(), 16.f / 9.f);
   auto b = view.build(reordered_scene_with_three_lights(), 16.f / 9.f);
@@ -54,14 +54,14 @@ Tasks 1–3 define the shared interfaces. Integrate Task 2's descriptor ABI befo
         "Light ordering follows stable IDs, not entity array order");
   ```
 - [ ] **Step 2: Run the focused tests red.** Run `cmake --preset linux-debug` and `cmake --build --preset linux-debug --target faset_authoring_tests faset_player_tests --parallel 4`; missing typed fields should fail compilation. If compilation succeeds, `ctest --test-dir build/linux-debug --output-on-failure --no-tests=error -R '^(authoring|player_scene_contracts)$'` must fail on a new behavioral assertion. Record the expected failure rather than assuming the build itself must be red.
-- [ ] **Step 3: Add schema defaults and extraction.** Keep builtin version 1; use `fields.value` for additive fields, normalize directions after the world transform, validate finite/color/range/cone values, sort by stable ID, and preserve the legacy fallback only when no authored light component exists. Set `camera_frustum` from the same unjittered view/projection used to form `view_projection`. Update direct C++ API examples to construct one point and one spot light.
+- [ ] **Step 3: Add schema defaults and extraction.** Keep builtin version 1; use `fields.value` for additive fields, normalize directions after the world transform, validate finite/color/range/cone values, sort by stable ID, and preserve the legacy fallback. Set `camera_frustum` from the same unjittered view/projection used to form `view_projection`. Update direct C++ API examples to construct one point and one spot light.
   ```cpp
   struct CameraFrustum {
       Mat4 view{identity}, projection{identity};
       float near_plane{0.1f}, far_plane{1000.f};
       bool perspective{true};
   };
-  // Snapshot::light_direction remains a fallback only if authored_lights_present is false.
+  // Snapshot::light_direction remains available to callers without Snapshot::sun.
   ```
 - [ ] **Step 4: Run focused tests green.** `ctest --test-dir build/linux-debug --output-on-failure -R '^(authoring|player_scene_contracts)$'` passes, including old version-1 scenes and exported-scene decoding.
 - [ ] **Step 5: Commit** `Expose authored sun, point, and spot lights in render snapshots`.

docs/superpowers/specs/2026-09-24-p3-lighting-design.md

@@ -12,7 +12,7 @@ P3 supplies one sun plus point and spot lights, camera-fitted cascaded sun shado
 
 Keep `faset.light` at builtin schema version 1 and add optional fields with defaults: `kind` (`directional`, `point`, `spot`, default `directional`), `enabled` (true), `color` (white), `intensity` (1, nonnegative), `range` (10, positive, for local lights), `inner_angle` (0.35 radians), `outer_angle` (0.70 radians, strictly below π/2), `casts_shadow` (true), and `shadow_priority` (integer 0). Existing fields and component IDs remain valid. Cross-field validation requires `0 <= inner_angle <= outer_angle`; local range, color channels, intensity, transforms, and cone directions must be finite. Invalid authored values return a diagnostic with entity and field rather than nonfinite GPU data. Missing new fields use the schema defaults.
 
-`Snapshot` retains `light_direction` for existing direct-render clients. Add an optional `SunLight`, a vector of `LocalLight`, an `authored_lights_present` flag (default false), and an optional explicit `CameraFrustum` containing unjittered view/projection matrices, near/far distances, and projection kind. `SceneView` populates these from the authoring scene and sets the flag if any authored light component exists, including a disabled or future-version component. Each light carries the stable entity/component identity, transformed position or normalized direction, color, intensity, range, cone angles, and shadow options. The first enabled directional light by stable ID is the sun; extra directionals produce a visible diagnostic until a later multi-sun design exists. The renderer synthesizes the legacy sun from `Snapshot::light_direction` only when `sun` is absent **and** `authored_lights_present` is false. Thus an old scene without light components keeps its previous appearance, while a local-only scene or explicitly disabled sun does not receive an unintended directional light. Low-level callers may set the flag to request a dark scene without authoring metadata. Local lights are ordered by stable ID to prevent reordering from changing atlas allocation or results. Point attenuation tends smoothly to zero at `range`; a spot multiplies it by a smooth inner-to-outer cone factor. The shader handles zero distance and invalid normals without NaN output.
+`Snapshot` retains `light_direction` for existing direct-render clients. Add an optional `SunLight`, a vector of `LocalLight`, and an optional explicit `CameraFrustum` containing unjittered view/projection matrices, near/far distances, and projection kind. `SceneView` populates these from the authoring scene. Each light carries the stable entity/component identity, transformed position or normalized direction, color, intensity, range, cone angles, and shadow options. The first enabled directional light by stable ID is the sun; extra directionals produce a visible diagnostic until a later multi-sun design exists. If there is no authored directional light, the renderer synthesizes the legacy sun from `Snapshot::light_direction`. Local lights are ordered by stable ID to prevent reordering from changing atlas allocation or results. Point attenuation tends smoothly to zero at `range`; a spot multiplies it by a smooth inner-to-outer cone factor. The shader handles zero distance and invalid normals without NaN output.
 
 Explicit camera frustum data is required for four cascades. If a low-level caller supplies only the legacy `view_projection`, the renderer uses one bounded legacy-compatible sun shadow view and reports `effective_sun_cascades = 1`; it never silently claims CSM. 2D sprite-only snapshots do not incur shadow work. The future temporal stage may jitter the main raster projection, but the shadow planner consumes the unjittered `CameraFrustum` exclusively.
 

docs/validation/README.md

@@ -5,7 +5,6 @@ These files preserve bounded checks and their inputs. Each record states its sou
 - [MVP acceptance dossier](mvp-acceptance.md): criterion-by-criterion closure, tested revisions and remaining compatibility coverage.
 - [P2 GPU visibility Linux evidence](p2-gpu-visibility-2026-09-23/README.md): Debug/Release GPU acceptance, lavapipe functional checks, relocated Player exports, and explicit platform/performance limits.
 - [P2 pinned SwiftShader compatibility](p2-swiftshader-2026-09-23/README.md): the Windows CI regression, shader capability fix, independent review closure, final native CI and relocated Player evidence.
-- [P3 lighting and shadows](p3-lighting-2026-09-24/README.md): implementation, Forward+ A/B and image parity, acceptance matrix, bounded Linux evidence, and remaining Windows/platform checks; temporal reconstruction is tracked separately.
 - [Windows software Vulkan](windows-software-vulkan-2026-09-18/README.md): fresh native build, 35 tests, launcher/window/MCP workflows and both relocated Release games on SwiftShader.
 - [Checkpoint 5 Linux acceptance](checkpoint5-linux-2026-09-18/README.md): clean offline source build, first Editor launch, exact-candidate standalone games and live Blender checks.
 - [Final Linux source checks](final-linux-2026-09-18/README.md): `4cb8255` integrated test results and both Release games after the asset-relocation correction, including package manifests and standalone captures.

docs/validation/lua-module.md

@@ -40,7 +40,7 @@ check. For sanitizers, configure with `-DFASET_SANITIZERS=ON`, build the
 `faset_lua_tests`, `faset_lua_safety_tests`, and `faset_schema_exporter` targets, then
 run `ctest --test-dir <build> --output-on-failure -R '^lua_'`.
 
-## Not verified here
+## Not verified in the September 18 run
 
 - Windows compilation or execution of the new module.
 - Graphical/window interaction and real-time Lua reload in a running rendered game.
@@ -53,3 +53,20 @@ run `ctest --test-dir <build> --output-on-failure -R '^lua_'`.
 The renderer-linked CPU checks used the existing Vulkan loader, repo-pinned Vulkan
 headers and cached Slang, with SDL X11/Wayland disabled. No system graphics packages
 were installed. This proves linkage and CPU validation, not graphics compatibility.
+
+## September 24 Release follow-up
+
+The [Release execution record](lua-release-2026-09-24/README.md) closes the
+Linux offscreen export gap above. At source commit `4331857`, a Release Editor
+exported the checked-in Lua-only sample into a disposable Unicode-path project.
+The package was relocated, the source project path was hidden, and its Player
+validated and rendered 120 frames on an NVIDIA GeForce RTX 2080 Ti with driver
+595.84 and Khronos validation enabled; zero validation errors were reported.
+The package manifest has `lua_enabled: true`, declared Lua source and its license,
+and no project C++ gameplay source. The five focused Release Lua/schema tests
+passed. This verifies an offscreen run on Linux; a separate physical Windows GPU
+and manual window interaction have not been tested by this record. Windows
+SwiftShader execution is configured in CI and needs a passing run before it is
+claimed as covered.
+
+![Relocated Lua sample after 120 frames](lua-release-2026-09-24/lua.png)

docs/validation/lua-release-2026-09-24/README.md

@@ -0,0 +1,52 @@
+# Lua-only Release game: relocated execution
+
+This is a local Linux result for source revision
+`433185717e1f324acb6eaf186818589d11697453` on 2026-09-24. The
+[machine-readable report](report.json) records the exact source input hashes,
+Release package, Editor binary hash, command arguments and elapsed times. The
+Editor itself was built with the `linux-release` preset. The exported Player
+and package also identify their configuration as Release.
+
+| Check | Observed result |
+|---|---|
+| Disposable source | `examples/lua` copied to a Unicode-path temporary project outside the engine tree |
+| Package | `lua_enabled: true`; 32 hash-checked files, including Lua gameplay source and `Notices/lua/LICENSE.txt`; no project `Gameplay.cpp` or `.hpp` |
+| Relocation | Generation copied outside the project/engine; original project path hidden before Player launch |
+| CPU validation | Packaged Player `--validate` succeeded from an unrelated empty working directory |
+| GPU execution | 120/120 headless 1280×720 frames, 0 validation errors |
+| Device | NVIDIA GeForce RTX 2080 Ti; proprietary driver 595.84, Vulkan 1.4.329; selected-device details in the report and [Vulkan probe](vulkaninfo-summary.txt) |
+| Image | Four expected scene colors, including cyan player and gold collectible; raw [PPM](lua.ppm) SHA-256 `e2f4c3b84de75dadd2e31d388d0ba51abc1861f1ec76eb7ba51a4a2dcac720a7` |
+| Focused Release CTest | 5/5: `lua_contracts`, `lua_safety_contracts`, `lua_cli_contracts`, `lua_player_reload`, `build_schema_publication` |
+
+The [manifest](lua-manifest.json) binds the package file checksums. The
+[Player profile](lua-profile.json) contains all 120 per-frame samples and
+resource/timing definitions; the [validate](lua-validate.json),
+[render](lua-run.json) and [export](lua-export.json) logs retain raw process
+results. The [PNG preview](lua.png) is a lossless conversion of the checked
+PPM.
+
+The verifier also confirmed a clean Git source tree, rejected undeclared
+package files and unexpected C++ script files, classified the selected device
+as physical, and found the sample Lua `on_start` log in the relocated run.
+
+To repeat this check from a built checkout, choose a **new, empty** output
+directory:
+
+```sh
+cmake --preset linux-release
+cmake --build --preset linux-release --target faset_editor --parallel 4
+python3 tools/verify_playable_exports.py --editor build/linux-release/faset_editor \
+  --output .cache/lua-release-check --only-lua
+cmake --build --preset linux-release --target faset_player faset_schema_exporter \
+  faset_lua_tests faset_lua_safety_tests faset_build_schema_tests --parallel 4
+ctest --test-dir build/linux-release --no-tests=error --output-on-failure \
+  -R '^(lua_contracts|lua_safety_contracts|lua_cli_contracts|lua_player_reload|build_schema_publication)$'
+```
+
+The render used the Player's synthetic fixed timestep and offscreen Vulkan
+presentation. It does not establish manual window interaction or physical
+Windows GPU compatibility. The Windows graphics workflow now includes this Lua
+package beside both C++ examples under a pinned SwiftShader Vulkan driver; its
+result must be recorded separately after CI completes.
+
+![Lua game rendered by the relocated Release Player](lua.png)

docs/validation/lua-release-2026-09-24/lua-manifest.json

@@ -0,0 +1,220 @@
+{
+  "asset_generations": {},
+  "build_fingerprint": "b745490f85f05987d849f6bb6f4d06953883f4b8e10c5551fadf164c7eec5857",
+  "configuration": "Release",
+  "executable": "faset_player",
+  "files": [
+    {
+      "path": "README.txt",
+      "sha256": "82bf72bc542643f6c4090e0a5de69b0014ca3fa17c6f9dfb12cc41e44c8b8db6",
+      "size": 262
+    },
+    {
+      "path": "Notices/Faset-NOTICE.txt",
+      "sha256": "30c2e7e80f5153b31ab57675e07246aef9165965d64e36022b426a26449ece3f",
+      "size": 204
+    },
+    {
+      "path": "Notices/dependencies.json",
+      "sha256": "262e8f63cf21c516829b1fedb0900ac90e76d62aa8f78d9ad02d8f24e0359e74",
+      "size": 2468
+    },
+    {
+      "path": "Notices/lua/LICENSE.txt",
+      "sha256": "e42d195c77d3ad7255ee9c874772d3c53998e7f60f9acf453d4630fa161e0bfe",
+      "size": 1126
+    },
+    {
+      "path": "Notices/stb/LICENSE",
+      "sha256": "bebfe904b14301657e4e5d655c811d51fd31b97c455b9cc2d8600d6bac6cff63",
+      "size": 2510
+    },
+    {
+      "path": "Notices/json/LICENSE.MIT",
+      "sha256": "46a65cffd1ea955132d95a8dd921640714a8d6b537d2e4e482d31145ae95b603",
+      "size": 1076
+    },
+    {
+      "path": "Notices/box3d/LICENSE",
+      "sha256": "da5e31a26bf3cfd5ba5c96d6823e480128c81e76c107ef9d3ee5d94789184b90",
+      "size": 1067
+    },
+    {
+      "path": "Notices/box2d/LICENSE",
+      "sha256": "68a3e676d7e94093b102d5cba0d4e04af812040d6f230c3db67a6664574e43d2",
+      "size": 1067
+    },
+    {
+      "path": "Notices/entt/LICENSE",
+      "sha256": "0785027ce472d7c61f05fba664a1d3ba6639c1593ced351ad9e4bed868765d99",
+      "size": 1097
+    },
+    {
+      "path": "Notices/sdl3/LICENSE.txt",
+      "sha256": "97f35b302b361680ec1e891e95d2d52097bb95abff361434916d99dc1305f127",
+      "size": 884
+    },
+    {
+      "path": "shaders/gpuPostCullMain.reflection.json",
+      "sha256": "eed140bbe09c7d14935b688c770261ac0e81677c0974aa811c88ed67ea779b95",
+      "size": 3591
+    },
+    {
+      "path": "shaders/gpuHzbMain.reflection.json",
+      "sha256": "589818f670881c64f3aba726ee3bc82fe4b9d835a347f99134e0e157dc4a112e",
+      "size": 2050
+    },
+    {
+      "path": "shaders/gpuCullMain.reflection.json",
+      "sha256": "996fe5c7e31c6b8f316d8f290b3be0ae7063eb46c500a661e8715e9b822a2598",
+      "size": 3587
+    },
+    {
+      "path": "shaders/gpuShadowMain.reflection.json",
+      "sha256": "9a03a2b692d2b0c758f63fb27760352cfef20a068372ebc137f1ca1797dcd3c2",
+      "size": 2755
+    },
+    {
+      "path": "shaders/gpuVertexMain.reflection.json",
+      "sha256": "9f43472c267dbb6a2ddc69e252f7f00c5ca46f376d3c7c27165c8d12a175179d",
+      "size": 3098
+    },
+    {
+      "path": "shaders/gpuPostCullMain.spv",
+      "sha256": "62cb72e356346e1511c6d640a3cecb4a6e5283795338299b357edae5f7f52be4",
+      "size": 12460
+    },
+    {
+      "path": "shaders/gpuHzbMain.spv",
+      "sha256": "08682362ee2120ed19d260e613285071747c3e436bb09bb6238e46f9cedc2308",
+      "size": 4140
+    },
+    {
+      "path": "shaders/gpuCullMain.spv",
+      "sha256": "7691360ec55f41d40d43652f506b051cef8b3a3ddcdcc7db61a7d4d97f9e87d8",
+      "size": 16180
+    },
+    {
+      "path": "shaders/gpuShadowMain.spv",
+      "sha256": "ffcdb91e70c41ce9452094865546a009b9203140cf8eeb3ad1b4e5868d82b815",
+      "size": 2404
+    },
+    {
+      "path": "shaders/gpuVertexMain.spv",
+      "sha256": "4647ef4fe1a68ab623ee9c19dac56631907f825cba0becd30869c5221c2a0385",
+      "size": 4928
+    },
+    {
+      "path": "shaders/shadowMain.reflection.json",
+      "sha256": "e3fd0889cd2f569d410f5d7558a4091d9f57f247a1dcf1788462f67525340819",
+      "size": 2645
+    },
+    {
+      "path": "shaders/fragmentMain.reflection.json",
+      "sha256": "72ebf8d32452830650416dc4717d89a4324e97ece7028dfb97c66803c8dce71f",
+      "size": 2649
+    },
+    {
+      "path": "shaders/vertexMain.reflection.json",
+      "sha256": "c584f3b957ebf194a292451362a98590f85ff3cfbfd8f917b1c1265039381777",
+      "size": 2639
+    },
+    {
+      "path": "shaders/shadowMain.spv",
+      "sha256": "7643b4d688492b5ee923b9606f0b0e70343ca05fa67673838206119a6f86d8d8",
+      "size": 784
+    },
+    {
+      "path": "shaders/fragmentMain.spv",
+      "sha256": "f5c4f289917ecab5d00d543c053aac1d10e6cca311fd172daf06d315160a3505",
+      "size": 7436
+    },
+    {
+      "path": "shaders/vertexMain.spv",
+      "sha256": "1ad2631c35d654f48166321ae43d4165043e1b919b14f1dc61caf97b1ada0898",
+      "size": 1224
+    },
+    {
+      "path": "faset_player",
+      "sha256": "99d7b8286a9151ec4eff9a9899e862d987048b031e1e40ca1938646afbde37bd",
+      "size": 6329192
+    },
+    {
+      "path": "project.faset.json",
+      "sha256": "e07b12047f8141c3c4cc8f0e7d0905a5c635375e4494755e34191db0859ab86f",
+      "size": 175
+    },
+    {
+      "path": "Scripts/util/motion.lua",
+      "sha256": "bad3dcdc1081fd1dec589c12dad8dc175b739d77ea52b957ead9ecb4b7cb88a3",
+      "size": 150
+    },
+    {
+      "path": "Scripts/player.lua",
+      "sha256": "1c51810574a3413c46a7cbd0ea2e84a9b802da1206a2b72bb78f6cc951367a11",
+      "size": 1376
+    },
+    {
+      "path": "Scripts/beacon.lua",
+      "sha256": "44d932ebedf66cadb9620f2d926177be2f8d43d71d56aa83611de686af026231",
+      "size": 820
+    },
+    {
+      "path": "scene.fscene",
+      "sha256": "641ba14a1f9c3966b9ec797814fdfa54f954dc5e0d53ab00c645598edef61baf",
+      "size": 1681
+    }
+  ],
+  "format": "faset.export",
+  "generation": "aa31bf16-984e-4854-b46f-15655bd6cc67",
+  "lua_enabled": true,
+  "lua_fingerprint": "a9261789bb1e0ca38bd40b08b0454165cd51454cba3ad4725dd357812ced6e35",
+  "platform": "linux",
+  "prerequisites": [
+    "Linux x86_64",
+    "Vulkan 1.3 driver",
+    "Compatible glibc and libstdc++ runtime"
+  ],
+  "renderer_profile": {
+    "api": "Vulkan 1.3",
+    "materials": [
+      "base-color factor and texture",
+      "metallic and roughness factors"
+    ],
+    "required_features": [
+      "dynamicRendering",
+      "synchronization2"
+    ],
+    "shadow_map": {
+      "resolution": 1024,
+      "world_extent": 40
+    },
+    "texture_sampling": "linear clamp, one mip level",
+    "unsupported_material_features": [
+      "normal maps",
+      "metallic-roughness maps",
+      "emissive and occlusion maps",
+      "alpha mode selection",
+      "unlit mode",
+      "per-material face culling"
+    ]
+  },
+  "scene_hash": "143724a468d711cbdf9a9700310d7b0acef003ce1b21422ca5204e0e565fa02c",
+  "simulation": {
+    "fixed_delta": 0.016666666666666666,
+    "gravity": [
+      0,
+      -9.81,
+      0
+    ],
+    "max_catch_up_ticks": 4,
+    "physics_substeps": 4
+  },
+  "units": {
+    "angle": "radian",
+    "coordinates": "right-handed Y-up",
+    "distance": "metre"
+  },
+  "validation_log": "{\"dimension\":2,\"validated\":true}\n",
+  "version": 1
+}

docs/validation/lua-release-2026-09-24/lua-run.json

@@ -0,0 +1,18 @@
+{
+  "arguments": [
+    "/tmp/faset-playable-exports-8wzkrc_u/Faset Café 世界/lua/faset_player",
+    "--headless",
+    "--frames",
+    "120",
+    "--capture",
+    "/tmp/faset-playable-exports-8wzkrc_u/Faset Café 世界/lua/verification.ppm",
+    "--profile",
+    "/tmp/faset-playable-exports-8wzkrc_u/Faset Café 世界/lua/profile.json"
+  ],
+  "cwd": "/tmp/faset-playable-exports-8wzkrc_u/empty-working-directory",
+  "seconds": 0.6288121230027173,
+  "exit_code": 0,
+  "timed_out": false,
+  "stdout": "{\"device\":\"NVIDIA GeForce RTX 2080 Ti\",\"dimension\":2,\"effective_visibility_mode\":\"direct\",\"frames\":120,\"gpu_visibility_active\":false,\"ticks\":120,\"validation_errors\":0,\"visibility_mode\":\"direct\"}\n",
+  "stderr": "Lua player ready: A/D move, Space jump, E reset\n"
+}

docs/validation/lua-release-2026-09-24/lua-validate.json

@@ -0,0 +1,12 @@
+{
+  "arguments": [
+    "/tmp/faset-playable-exports-8wzkrc_u/Faset Café 世界/lua/faset_player",
+    "--validate"
+  ],
+  "cwd": "/tmp/faset-playable-exports-8wzkrc_u/empty-working-directory",
+  "seconds": 0.007359832990914583,
+  "exit_code": 0,
+  "timed_out": false,
+  "stdout": "{\"dimension\":2,\"validated\":true}\n",
+  "stderr": ""
+}

docs/validation/lua-release-2026-09-24/report.json

@@ -0,0 +1,134 @@
+{
+  "format": "faset.playable-export-verification",
+  "version": 1,
+  "started_utc": "2026-09-23T23:30:12.719805+00:00",
+  "platform": "linux",
+  "engine": "/home/emil/Desktop/.worktrees/Faset_Engine-p1-lua-export",
+  "editor": "/home/emil/Desktop/.worktrees/Faset_Engine-p1-lua-export/build/linux-release/faset_editor",
+  "standalone_root": "/tmp/faset-playable-exports-8wzkrc_u",
+  "engine_revision": "433185717e1f324acb6eaf186818589d11697453",
+  "engine_dirty": false,
+  "engine_git_status": [],
+  "engine_diff_sha256": null,
+  "editor_sha256": "03ac75942f5f1d29e9d6fedb21ecffc6c74f4299401dbe84f01ab1b4e9c176a0",
+  "project_workspace": "/tmp/faset-playable-projects-cuhq4iwr",
+  "vulkaninfo_available": true,
+  "driver_override": null,
+  "frames_per_game": 120,
+  "status": "passed",
+  "projects": [
+    {
+      "name": "lua",
+      "dimension": 2,
+      "language": "lua",
+      "source_inputs": [
+        {
+          "path": "README.md",
+          "sha256": "8392da3c18916400ea628daed094c77c390c553cbdcf822da227bdcd3d86380c"
+        },
+        {
+          "path": "Scenes/main.scene.json",
+          "sha256": "f1ab54150a58b289c47bcc34566ad7ee3025ad931db81e7f5dce70d9fbcac8ab"
+        },
+        {
+          "path": "Scripts/beacon.lua",
+          "sha256": "44d932ebedf66cadb9620f2d926177be2f8d43d71d56aa83611de686af026231"
+        },
+        {
+          "path": "Scripts/player.lua",
+          "sha256": "1c51810574a3413c46a7cbd0ea2e84a9b802da1206a2b72bb78f6cc951367a11"
+        },
+        {
+          "path": "Scripts/util/motion.lua",
+          "sha256": "bad3dcdc1081fd1dec589c12dad8dc175b739d77ea52b957ead9ecb4b7cb88a3"
+        },
+        {
+          "path": "project.faset.json",
+          "sha256": "7e4c0781c1837208b4499a9991ffb702143edf1f933ae9c7e3d2543fd2577747"
+        }
+      ],
+      "generation": "aa31bf16-984e-4854-b46f-15655bd6cc67",
+      "configuration": "Release",
+      "standalone_directory": "/tmp/faset-playable-exports-8wzkrc_u/Faset Café 世界/lua",
+      "executable": "faset_player",
+      "package_file_count": 32,
+      "asset_generations": {},
+      "device": "NVIDIA GeForce RTX 2080 Ti",
+      "device_class": "physical",
+      "driver": {
+        "apiVersion": "1.4.329",
+        "driverVersion": "595.84.0.0",
+        "deviceName": "NVIDIA GeForce RTX 2080 Ti",
+        "driverID": "DRIVER_ID_NVIDIA_PROPRIETARY",
+        "driverName": "NVIDIA",
+        "driverInfo": "595.84"
+      },
+      "validation_enabled": true,
+      "validation_errors": 0,
+      "completed_frames": 120,
+      "summary_ms": {
+        "gpu": {
+          "max": 0.584992,
+          "min": 0.551712,
+          "p50": 0.5608,
+          "p95": 0.574592,
+          "samples": 120
+        },
+        "render_call": {
+          "max": 4.928888,
+          "min": 1.544123,
+          "p50": 1.919881,
+          "p95": 2.423702,
+          "samples": 120
+        },
+        "renderer_cpu": {
+          "max": 4.923196,
+          "min": 1.540666,
+          "p50": 1.915753,
+          "p95": 2.420426,
+          "samples": 120
+        },
+        "renderer_readback_cpu": {
+          "max": 2.837363,
+          "min": 0.395756,
+          "p50": 0.504853,
+          "p95": 0.641169,
+          "samples": 120
+        },
+        "simulation": {
+          "max": 0.210056,
+          "min": 0.084289,
+          "p50": 0.122261,
+          "p95": 0.171062,
+          "samples": 120
+        },
+        "snapshot": {
+          "max": 0.254931,
+          "min": 0.046518,
+          "p50": 0.065754,
+          "p95": 0.087906,
+          "samples": 120
+        },
+        "wall": {
+          "max": 5.322149,
+          "min": 1.702973,
+          "p50": 2.142903,
+          "p95": 2.634219,
+          "samples": 120
+        }
+      },
+      "capture": {
+        "width": 1280,
+        "height": 720,
+        "sampled_colors": 4,
+        "sha256": "e2f4c3b84de75dadd2e31d388d0ba51abc1861f1ec76eb7ba51a4a2dcac720a7"
+      },
+      "source_project_paths_unavailable": true,
+      "status": "passed"
+    }
+  ],
+  "requested_projects": [
+    "lua"
+  ],
+  "finished_utc": "2026-09-23T23:32:18.151669+00:00"
+}

docs/validation/lua-release-2026-09-24/vulkaninfo-summary.txt

@@ -0,0 +1,82 @@
+==========
+VULKANINFO
+==========
+
+Vulkan Instance Version: 1.4.341
+
+
+Instance Extensions: count = 27
+-------------------------------
+VK_EXT_acquire_drm_display             : extension revision 1
+VK_EXT_acquire_xlib_display            : extension revision 1
+VK_EXT_debug_report                    : extension revision 10
+VK_EXT_debug_utils                     : extension revision 2
+VK_EXT_direct_mode_display             : extension revision 1
+VK_EXT_display_surface_counter         : extension revision 1
+VK_EXT_headless_surface                : extension revision 1
+VK_EXT_layer_settings                  : extension revision 2
+VK_EXT_surface_maintenance1            : extension revision 1
+VK_EXT_swapchain_colorspace            : extension revision 5
+VK_KHR_device_group_creation           : extension revision 1
+VK_KHR_display                         : extension revision 23
+VK_KHR_external_fence_capabilities     : extension revision 1
+VK_KHR_external_memory_capabilities    : extension revision 1
+VK_KHR_external_semaphore_capabilities : extension revision 1
+VK_KHR_get_display_properties2         : extension revision 1
+VK_KHR_get_physical_device_properties2 : extension revision 2
+VK_KHR_get_surface_capabilities2       : extension revision 1
+VK_KHR_portability_enumeration         : extension revision 1
+VK_KHR_surface                         : extension revision 25
+VK_KHR_surface_maintenance1            : extension revision 1
+VK_KHR_surface_protected_capabilities  : extension revision 1
+VK_KHR_wayland_surface                 : extension revision 6
+VK_KHR_xcb_surface                     : extension revision 6
+VK_KHR_xlib_surface                    : extension revision 6
+VK_LUNARG_direct_driver_loading        : extension revision 1
+VK_NV_display_stereo                   : extension revision 1
+
+Instance Layers: count = 12
+---------------------------
+VK_LAYER_INTEL_nullhw             INTEL NULL HW                                                1.1.73   version 1
+VK_LAYER_KHRONOS_validation       Khronos Validation Layer                                     1.4.341  version 1
+VK_LAYER_MESA_anti_lag            Open-source implementation of the VK_AMD_anti_lag extension. 1.4.303  version 1
+VK_LAYER_MESA_device_select       Linux device selection layer                                 1.4.303  version 1
+VK_LAYER_MESA_overlay             Mesa Overlay layer                                           1.4.303  version 1
+VK_LAYER_MESA_screenshot          Mesa Screenshot layer                                        1.4.303  version 1
+VK_LAYER_NV_optimus               NVIDIA Optimus layer                                         1.4.329  version 1
+VK_LAYER_NV_present               NVIDIA Presentation Layer                                    1.4.329  version 1
+VK_LAYER_VALVE_steam_fossilize_32 Steam Pipeline Caching Layer                                 1.3.207  version 1
+VK_LAYER_VALVE_steam_fossilize_64 Steam Pipeline Caching Layer                                 1.3.207  version 1
+VK_LAYER_VALVE_steam_overlay_32   Steam Overlay Layer                                          1.3.207  version 1
+VK_LAYER_VALVE_steam_overlay_64   Steam Overlay Layer                                          1.3.207  version 1
+
+Devices:
+========
+GPU0:
+	apiVersion         = 1.4.329
+	driverVersion      = 595.84.0.0
+	vendorID           = 0x10de
+	deviceID           = 0x1e04
+	deviceType         = PHYSICAL_DEVICE_TYPE_DISCRETE_GPU
+	deviceName         = NVIDIA GeForce RTX 2080 Ti
+	driverID           = DRIVER_ID_NVIDIA_PROPRIETARY
+	driverName         = NVIDIA
+	driverInfo         = 595.84
+	conformanceVersion = 1.4.3.3
+	deviceUUID         = 2c71c7ba-97ac-c78e-2c06-af362631f3fe
+	driverUUID         = 027cbdd1-c478-513e-af69-ebc9eaa7de87
+GPU1:
+	apiVersion         = 1.4.335
+	driverVersion      = 26.0.8
+	vendorID           = 0x10005
+	deviceID           = 0x0000
+	deviceType         = PHYSICAL_DEVICE_TYPE_CPU
+	deviceName         = llvmpipe (LLVM 21.1.8, 256 bits)
+	driverID           = DRIVER_ID_MESA_LLVMPIPE
+	driverName         = llvmpipe
+	driverInfo         = Mesa 26.0.8-1ubuntu0.3 (LLVM 21.1.8)
+	conformanceVersion = 1.3.1.1
+	deviceUUID         = 6d657361-3236-2e30-2e38-2d3175627500
+	driverUUID         = 6c6c766d-7069-7065-5555-494400000000
+WARNING: [Loader Message] Code 0 : ICD for selected physical device does not export vkGetPhysicalDeviceDisplayPlanePropertiesKHR!
+WARNING: [Loader Message] Code 0 : ICD for selected physical device does not export vkGetPhysicalDeviceDisplayPropertiesKHR!

docs/validation/p1-starters-linux-2026-09-24.md

@@ -0,0 +1,42 @@
+# P1 starter projects: Linux checkpoint (2026-09-24)
+
+This is a focused validation of the four explicit new-project choices in commit
+`cbb8b4508723e1a3a0bbd53c884e116a47b121dc`. It is not the final P1 acceptance
+record. The run used Linux 7.0.0-31-generic x86_64, Clang 21.1.8, CMake 4.2.3,
+and an NVIDIA GeForce RTX 2080 Ti with driver 595.84.
+
+The Editor CLI created C++ 2D, C++ 3D, Lua 2D, and Lua 3D projects in disposable
+directories with `--new`, `--dimension`, and `--language`. The test checked the
+project manifest, authored start scene, behavior binding, Lua script declaration,
+LuaLS files, and the absence of a C++ gameplay stub in Lua-only projects. A real
+Debug `faset_build` succeeded for C++ 2D and Lua 3D. Their built Players then
+validated and rendered **both** corresponding scene dimensions using the same
+language module, so all four templates exercised runtime schema and rendering.
+Each headless one-frame render reported `validation_errors: 0` on the physical GPU.
+
+| Project | Built Player used | `--validate` | One-frame headless render |
+| --- | --- | --- | --- |
+| C++ 2D | C++ 2D | passed | passed |
+| C++ 3D | C++ 2D | passed | passed |
+| Lua 2D | Lua 3D | passed | passed |
+| Lua 3D | Lua 3D | passed | passed |
+
+The C++ and Lua source files are identical within each language choice; the 2D/3D
+difference is the authored scene. Reusing one built Player per language therefore
+checks scene validity without repeating an identical native compile. The focused
+CTest cases `process_and_cook` and `editor_ui_launcher` passed 2/2. They include a
+two-service concurrent creation test: exactly one starter wins, and the other
+cannot overwrite it. A fresh Lua starter was initialized as a Git repository;
+`git check-ignore` confirmed `.faset/cache` is ignored while the LuaLS API
+declaration `.faset/lua/faset.lua` can be committed. A strict MkDocs build passed.
+
+These captures are representative output from the C++ 2D and 3D scenes. Lua
+scenes rendered the same layout with their own behavior module.
+
+![C++ 2D starter after one frame](p1-starters-linux-2026-09-24/cpp-2.png)
+
+![C++ 3D starter after one frame](p1-starters-linux-2026-09-24/cpp-3.png)
+
+The run did not test Windows, a relocated Release export, multi-frame gameplay
+input, or the final P1 build-cache integration. Those belong to the P1 acceptance
+matrix and must be recorded separately.

docs/validation/p3-lighting-2026-09-24/README.md

@@ -1,124 +0,0 @@
-# P3 lighting and shadows — acceptance record
-
-This record tracks P3 lighting separately from temporal reconstruction. The
-implementation and measured Forward+ checkpoint is source revision
-`a0a4e29d480ed3344f19bd3565d48668ca913fed` on `feat/p3-lighting`.
-The earlier shadow/benchmark integration checkpoint was `b191ae0`. The
-lighting slice has Linux functional and reference-GPU evidence; Windows CI for
-the new tiled revision is pending. Temporal reconstruction has its own acceptance.
-
-## Implemented at the checkpoint
-
-- Authored directional, point, and spot lights are extracted from the same
-  versioned Light schema used by the Inspector and MCP. No authored Light
-  component retains the legacy sun; any authored Light, including disabled or
-  local-only, suppresses that fallback.
-- Direct, GPU frustum, and GPU occlusion graphics paths use the same typed
-  lighting data. Material descriptors remain set 0, lighting set 1, and GPU
-  graphics scene data set 2. Sun and local light contributions accumulate before
-  tone mapping. Sprites and UI remain unlit.
-- Four texel-snapped sun cascades cover up to 80 world units for an explicit
-  camera frustum. A low-level Snapshot without one keeps a single sun view.
-  Shadow caster selection uses each light view and source LOD 0, independent of
-  camera visibility and prepared camera LOD. Missing/disabled sun and sprite-only
-  scenes skip sun shadow raster.
-- The separate D32 local atlas admits 16 faces, one per spot or six atomically
-  per point. Both shadow systems share a 4096-caster-draw frame budget. Up to 128
-  local lights are submitted by priority, projected influence, then stable ID.
-  Overflow or unsupported-atlas lights remain unshadowed when submitted; omitted
-  lights beyond 128 do not illuminate. Both atlases try 2048², then 1024².
-- The editor overlay and Player profile expose actual submitted/omitted lights,
-  requested/effective views, drop reasons, atlas bytes, caster draws, GPU shadow
-  durations, and the effective lighting path. Shadow tiles are redrawn every
-  frame; no persistent depth cache is claimed.
-- An explicit 16×16 depth-free tiled Forward+ path uses at most 64 light indices
-  per tile and evaluates the complete submitted list on overflow. The compute
-  entry has checked reflection and is included in game builds. `Auto` uses
-  forward: three-run Release measurements found tile build + raster slower on
-  the dense fixed scene. The [paired study](../../studies/23-p3-forward-plus-2026-09-24.md)
-  retains a separate localized-light win and exact binary/shader provenance.
-
-## Acceptance matrix
-
-| Case | Automated evidence | Current status |
-| --- | --- | --- |
-| Empty, disabled, local-only, multiple sun; schema bounds | `scene_view`, `render_lighting_policy`, `render_offscreen` | Linux Debug green at `a0a4e29`; integrated revision pending |
-| Four cascades, split bounds, subtexel stabilization, offscreen/source-LOD0 caster | `render_lighting_policy`, `render_lighting_sun` | Linux GPU and pinned SwiftShader P3 green at `a0a4e29` |
-| Spot cone, six point faces and seam, dropped whole point shadow | `render_lighting_local`, `render_lighting_policy` | Linux GPU and pinned SwiftShader P3 green at `a0a4e29` |
-| 128-light/16-face/4096-draw limits, unsupported-atlas fallback | `render_lighting_policy`, `render_offscreen`, `render_lighting_local` | CPU and supported-atlas GPU paths covered; actual unsupported Vulkan device not tested |
-| Direct/GPU frustum/GPU occlusion image parity, P2 reload and 2D/UI independence | `render_lighting_sun`, `render_lighting_local`, `render_shader_reload`, `render_offscreen` | Linux Debug green at `a0a4e29`; integrated revision pending |
-| Forward+/forward parity, near plane, resize, overflow, and shader reload | `render_lighting_tiled`, `render_shader_reload`, `render_shader_reflection`, `build_schema_publication` | Linux Debug and pinned SwiftShader P3 green at `a0a4e29`; 128-light localized Release captures match exactly |
-| Driver, profile, real 64×64 benchmark smoke | `render_lighting_benchmark_schema`, `render_lighting_benchmark_smoke`, `player_shutdown_diagnostics` | Full Linux Debug green at `a0a4e29` |
-| 1920×1080 0/4/16/32/64/128 Release sweep, three repeats, both shadow states | `tools/benchmark_p3_lighting.py --sweep` | Forward baseline measured; its separate raw study is being integrated |
-| 1920×1080 paired paths, 32/64/128 dense and localized lights | `faset_p3_lighting_benchmark --lighting forward|tiled` | Raw 1080 frames and six diagnostic samples retained in study 23; dense slower, localized faster by build+raster |
-| Windows native build, pinned SwiftShader GPU tests, relocated Release 2D/3D Players | `windows-graphics.yml`, `ci.yml` | New P3 revision has not yet completed Windows CI |
-
-The supported-atlas GPU tests create a renderer with validation requested and
-assert zero reported Vulkan errors; a test result is a validation-layer pass only
-when the layer was actually active. `render_window_lifecycle` can skip if the
-Linux compositor declines programmatic restore. The Windows workflow uses pinned
-SwiftShader, not a physical Windows GPU, and may lack the Khronos layer. Linux
-reference-GPU results cannot establish physical Windows performance.
-
-## Reproduction and retained evidence
-
-The P3 CTest registrations are `render_lighting_policy` and
-`render_lighting_benchmark_schema` (CPU), plus `render_lighting_sun`,
-`render_lighting_local`, `render_lighting_tiled`, and
-`render_lighting_benchmark_smoke` (labelled `gpu;p3`). Use
-`ctest --test-dir build/linux-debug -N -L p3` to confirm those six cases exist
-before running them; an empty test selection is not a pass.
-The Windows full graphics job runs all registered tests, while the native
-Windows CPU job uses `-LE gpu` and therefore excludes the four Vulkan cases.
-
-On the Linux host at `b191ae0`, the [CTest inventory](linux-debug-p3-inventory.txt)
-listed all five cases. The [CPU-only P3 run](linux-debug-cpu-ctest.txt) passed
-`render_lighting_policy` and `render_lighting_benchmark_schema` 2/2 with zero
-failures. The [strict MkDocs build](strict-mkdocs.txt) passed for these Manual
-changes. This run deliberately excluded Vulkan tests while the 1920×1080
-physical-GPU baseline was being measured, so it is not a final GPU acceptance
-result. The local host was Linux x86_64, kernel 7.0.0-31-generic; the source
-checkout had documentation changes only during these checks.
-
-At `a0a4e29`, the [full Linux Debug run](linux-debug-tiled-ctest.txt) had
-63 registered cases: 62 passed, no failures, and the compositor-dependent
-window lifecycle case skipped. The [pinned Linux SwiftShader P3 run](linux-swiftshader-tiled-p3-ctest.txt)
-passed all six P3 cases without a skip. The Vulkan image cases requested
-validation and asserted zero reported errors. The RTX 2080 Ti A/B used NVIDIA
-driver 595.84.0.0; study 23 records the executable and shader bundle hashes,
-all raw per-frame timings, tile overflow counts, and exact image equality for
-the localized 128-light capture. Its first dense 32-light forward run was an
-outlier, so the decision uses the median of three process medians rather than
-the apparent win in one paired run.
-
-At the earlier `b191ae0` checkpoint, [GitHub native/manual CI](https://github.com/emil28092005/Faset_Engine/actions/runs/35935899512)
-and [Windows graphics/SwiftShader CI](https://github.com/emil28092005/Faset_Engine/actions/runs/35935899505)
-passed. These jobs did **not** include the new tile shader; Windows CI for
-`a0a4e29` is still required.
-
-```sh
-cmake --build --preset linux-debug --parallel 2
-ctest --test-dir build/linux-debug -L p3 --no-tests=error --output-on-failure
-ctest --test-dir build/linux-debug --output-on-failure
-cmake --build --preset linux-release --parallel 2
-ctest --test-dir build/linux-release --output-on-failure
-```
-
-The benchmark wrapper retains one raw CSV per run, a merged CSV, and a summary.
-It rejects visibility fallback, missing GPU timestamps, missing lights, duplicate
-frames, and validation errors. An offscreen capture's `cpu_ms` includes GPU wait
-and readback; it is not thread CPU time. The exact Release benchmark revision,
-driver and paired path data are retained in study 23. Release full CTest,
-final integrated Windows Actions and relocated Player checks still need to be
-added before this is a complete P3 lighting acceptance record.
-
-## Limits carried forward
-
-The default path scans all submitted lights in each mesh fragment; the
-measured Forward+ threshold prompted a bounded tiled implementation. `Auto`
-still uses forward because this dense fixed workload was slower after tile
-construction. Transparent/game UI and sprites keep their existing
-ordering and unlit behavior. The atlas caps are fixed budgets, not adaptive
-quality settings, and shadow depth is redrawn each frame. The renderer still
-performs synchronous framebuffer readback. No broad scene/driver matrix or
-physical Windows GPU performance claim follows from these fixtures.

docs/validation/p3-lighting-2026-09-24/linux-debug-cpu-ctest.txt

@@ -1,12 +0,0 @@
-Test project /home/emil/Desktop/.worktrees/Faset_Engine-p3-lighting/build/linux-debug
-    Start  9: render_lighting_policy
-1/2 Test  #9: render_lighting_policy .............   Passed    0.04 sec
-    Start 17: render_lighting_benchmark_schema
-2/2 Test #17: render_lighting_benchmark_schema ...   Passed    4.95 sec
-
-100% tests passed, 0 tests failed out of 2
-
-Label Time Summary:
-p3    =   4.99 sec*proc (2 tests)
-
-Total Test time (real) =   5.00 sec

docs/validation/p3-lighting-2026-09-24/linux-debug-p3-inventory.txt

@@ -1,8 +0,0 @@
-Test project /home/emil/Desktop/.worktrees/Faset_Engine-p3-lighting/build/linux-debug
-  Test  #7: render_lighting_sun
-  Test  #8: render_lighting_local
-  Test  #9: render_lighting_policy
-  Test #17: render_lighting_benchmark_schema
-  Test #18: render_lighting_benchmark_smoke
-
-Total Tests: 5

docs/validation/p3-lighting-2026-09-24/linux-debug-tiled-ctest.txt

@@ -1,140 +0,0 @@
-Test project /home/emil/Desktop/.worktrees/Faset_Engine-p3-lighting/build/linux-debug
-      Start  1: authoring
- 1/63 Test  #1: authoring ..........................   Passed    0.06 sec
-      Start  2: runtime_contracts
- 2/63 Test  #2: runtime_contracts ..................   Passed    0.12 sec
-      Start  3: assets_pipeline
- 3/63 Test  #3: assets_pipeline ....................   Passed    0.14 sec
-      Start  4: assets_blender_bundle
- 4/63 Test  #4: assets_blender_bundle ..............   Passed    0.08 sec
-      Start  5: lua_contracts
- 5/63 Test  #5: lua_contracts ......................   Passed    0.11 sec
-      Start  6: lua_safety_contracts
- 6/63 Test  #6: lua_safety_contracts ...............   Passed    0.21 sec
-      Start  7: render_lighting_sun
- 7/63 Test  #7: render_lighting_sun ................   Passed    0.92 sec
-      Start  8: render_lighting_local
- 8/63 Test  #8: render_lighting_local ..............   Passed    0.87 sec
-      Start  9: render_lighting_tiled
- 9/63 Test  #9: render_lighting_tiled ..............   Passed    2.75 sec
-      Start 10: render_lighting_policy
-10/63 Test #10: render_lighting_policy .............   Passed    0.04 sec
-      Start 11: render_graph
-11/63 Test #11: render_graph .......................   Passed    0.00 sec
-      Start 12: render_offscreen
-12/63 Test #12: render_offscreen ...................   Passed    0.43 sec
-      Start 13: render_sprite_alpha
-13/63 Test #13: render_sprite_alpha ................   Passed    0.36 sec
-      Start 14: render_shader_reload
-14/63 Test #14: render_shader_reload ...............   Passed    4.49 sec
-      Start 15: render_gpu_shader_contract
-15/63 Test #15: render_gpu_shader_contract .........   Passed    0.06 sec
-      Start 16: render_shader_reflection
-16/63 Test #16: render_shader_reflection ...........   Passed    3.63 sec
-      Start 17: render_window_lifecycle
-17/63 Test #17: render_window_lifecycle ............***Skipped   4.02 sec
-      Start 18: render_lighting_benchmark_schema
-18/63 Test #18: render_lighting_benchmark_schema ...   Passed    4.02 sec
-      Start 19: render_lighting_benchmark_smoke
-19/63 Test #19: render_lighting_benchmark_smoke ....   Passed    0.44 sec
-      Start 20: visibility_policy
-20/63 Test #20: visibility_policy ..................   Passed    0.01 sec
-      Start 21: gpu_visibility
-21/63 Test #21: gpu_visibility .....................   Passed    0.90 sec
-      Start 22: render_gpu_empty
-22/63 Test #22: render_gpu_empty ...................   Passed    0.59 sec
-      Start 23: render_gpu_capacity
-23/63 Test #23: render_gpu_capacity ................   Passed    0.65 sec
-      Start 24: render_gpu_dense
-24/63 Test #24: render_gpu_dense ...................   Passed    0.64 sec
-      Start 25: render_gpu_door
-25/63 Test #25: render_gpu_door ....................   Passed    0.60 sec
-      Start 26: render_gpu_shadow
-26/63 Test #26: render_gpu_shadow ..................   Passed    0.60 sec
-      Start 27: render_gpu_cut
-27/63 Test #27: render_gpu_cut .....................   Passed    0.60 sec
-      Start 28: render_gpu_resize
-28/63 Test #28: render_gpu_resize ..................   Passed    0.63 sec
-      Start 29: render_gpu_lod
-29/63 Test #29: render_gpu_lod .....................   Passed    0.66 sec
-      Start 30: render_gpu_teleport
-30/63 Test #30: render_gpu_teleport ................   Passed    0.61 sec
-      Start 31: render_gpu_near
-31/63 Test #31: render_gpu_near ....................   Passed    0.61 sec
-      Start 32: render_gpu_lifecycle
-32/63 Test #32: render_gpu_lifecycle ...............   Passed    1.32 sec
-      Start 33: render_gpu_views
-33/63 Test #33: render_gpu_views ...................   Passed    0.59 sec
-      Start 34: render_gpu_projection
-34/63 Test #34: render_gpu_projection ..............   Passed    0.57 sec
-      Start 35: render_gpu_open_sequence
-35/63 Test #35: render_gpu_open_sequence ...........   Passed    1.80 sec
-      Start 36: render_gpu_transparent
-36/63 Test #36: render_gpu_transparent .............   Passed    0.62 sec
-      Start 37: player_scene_contracts
-37/63 Test #37: player_scene_contracts .............   Passed    0.03 sec
-      Start 38: player_shutdown_diagnostics
-38/63 Test #38: player_shutdown_diagnostics ........   Passed    1.53 sec
-      Start 39: lua_cli_contracts
-39/63 Test #39: lua_cli_contracts ..................   Passed    0.13 sec
-      Start 40: lua_player_reload
-40/63 Test #40: lua_player_reload ..................   Passed    2.45 sec
-      Start 41: editor_mcp
-41/63 Test #41: editor_mcp .........................   Passed    0.01 sec
-      Start 42: process_and_cook
-42/63 Test #42: process_and_cook ...................   Passed    0.32 sec
-      Start 43: build_schema_publication
-43/63 Test #43: build_schema_publication ...........   Passed    9.27 sec
-      Start 44: editor_plugins
-44/63 Test #44: editor_plugins .....................   Passed    0.03 sec
-      Start 45: editor_session_settings
-45/63 Test #45: editor_session_settings ............   Passed    0.02 sec
-      Start 46: ui_widgets
-46/63 Test #46: ui_widgets .........................   Passed    0.12 sec
-      Start 47: ui_render
-47/63 Test #47: ui_render ..........................   Passed    0.48 sec
-      Start 48: editor_ui_import_conflicts
-48/63 Test #48: editor_ui_import_conflicts .........   Passed    0.82 sec
-      Start 49: editor_ui_project_settings
-49/63 Test #49: editor_ui_project_settings .........   Passed    0.97 sec
-      Start 50: editor_ui_reload
-50/63 Test #50: editor_ui_reload ...................   Passed    4.04 sec
-      Start 51: editor_ui_launcher
-51/63 Test #51: editor_ui_launcher .................   Passed    0.84 sec
-      Start 52: editor_ui_templates
-52/63 Test #52: editor_ui_templates ................   Passed    2.48 sec
-      Start 53: editor_ui_gizmos
-53/63 Test #53: editor_ui_gizmos ...................   Passed    0.92 sec
-      Start 54: editor_ui_authoring
-54/63 Test #54: editor_ui_authoring ................   Passed    1.71 sec
-      Start 55: editor_mcp_stdio
-55/63 Test #55: editor_mcp_stdio ...................   Passed    0.27 sec
-      Start 56: editor_gui_mcp
-56/63 Test #56: editor_gui_mcp .....................   Passed    4.65 sec
-      Start 57: core
-57/63 Test #57: core ...............................   Passed    0.16 sec
-      Start 58: tutorial_moving
-58/63 Test #58: tutorial_moving ....................   Passed    0.02 sec
-      Start 59: tutorial_following
-59/63 Test #59: tutorial_following .................   Passed    0.01 sec
-      Start 60: tutorial_spawning
-60/63 Test #60: tutorial_spawning ..................   Passed    0.02 sec
-      Start 61: tutorial_physics
-61/63 Test #61: tutorial_physics ...................   Passed    0.06 sec
-      Start 62: playable_2d
-62/63 Test #62: playable_2d ........................   Passed    0.40 sec
-      Start 63: playable_3d
-63/63 Test #63: playable_3d ........................   Passed    0.93 sec
-
-100% tests passed, 0 tests failed out of 63
-
-Label Time Summary:
-gpu       =  47.20 sec*proc (35 tests)
-p2        =  12.02 sec*proc (16 tests)
-p3        =   9.05 sec*proc (6 tests)
-window    =   8.67 sec*proc (2 tests)
-
-Total Test time (real) =  67.51 sec
-
-The following tests did not run:
-	 17 - render_window_lifecycle (Skipped)

docs/validation/p3-lighting-2026-09-24/linux-swiftshader-tiled-p3-ctest.txt

@@ -1,21 +0,0 @@
-Test project /home/emil/Desktop/.worktrees/Faset_Engine-p3-lighting/build/linux-debug
-    Start  7: render_lighting_sun
-1/6 Test  #7: render_lighting_sun ................   Passed    5.14 sec
-    Start  8: render_lighting_local
-2/6 Test  #8: render_lighting_local ..............   Passed    4.76 sec
-    Start  9: render_lighting_tiled
-3/6 Test  #9: render_lighting_tiled ..............   Passed   14.30 sec
-    Start 10: render_lighting_policy
-4/6 Test #10: render_lighting_policy .............   Passed    0.03 sec
-    Start 18: render_lighting_benchmark_schema
-5/6 Test #18: render_lighting_benchmark_schema ...   Passed    4.04 sec
-    Start 19: render_lighting_benchmark_smoke
-6/6 Test #19: render_lighting_benchmark_smoke ....   Passed    1.23 sec
-
-100% tests passed, 0 tests failed out of 6
-
-Label Time Summary:
-gpu    =  25.42 sec*proc (4 tests)
-p3     =  29.50 sec*proc (6 tests)
-
-Total Test time (real) =  29.50 sec

docs/validation/p3-lighting-2026-09-24/strict-mkdocs-tiled.txt

@@ -1,20 +0,0 @@
-warning: An executable named `mkdocs` is not provided by package `mkdocs-material` but is available via the dependency `mkdocs`. Consider using `uvx --from mkdocs mkdocs` instead.
-
- │  ⚠  Warning from the Material for MkDocs team
- │
- │  MkDocs 2.0, the underlying framework of Material for MkDocs,
- │  will introduce backward-incompatible changes, including:
- │
- │  × All plugins will stop working – the plugin system has been removed
- │  × All theme overrides will break – the theming system has been rewritten
- │  × No migration path exists – existing projects cannot be upgraded
- │  × Closed contribution model – community members can't report bugs
- │  × Currently unlicensed – unsuitable for production use
- │
- │  Our full analysis:
- │
- │  https://squidfunk.github.io/mkdocs-material/blog/2026/02/18/mkdocs-2.0/
-
-INFO    -  Cleaning site directory
-INFO    -  Building documentation to directory: /home/emil/Desktop/.worktrees/Faset_Engine-p3-lighting/build/manual
-INFO    -  Documentation built in 0.76 seconds

docs/validation/p3-lighting-2026-09-24/strict-mkdocs.txt

@@ -1,20 +0,0 @@
-warning: An executable named `mkdocs` is not provided by package `mkdocs-material` but is available via the dependency `mkdocs`. Consider using `uvx --from mkdocs mkdocs` instead.
-
- │  ⚠  Warning from the Material for MkDocs team
- │
- │  MkDocs 2.0, the underlying framework of Material for MkDocs,
- │  will introduce backward-incompatible changes, including:
- │
- │  × All plugins will stop working – the plugin system has been removed
- │  × All theme overrides will break – the theming system has been rewritten
- │  × No migration path exists – existing projects cannot be upgraded
- │  × Closed contribution model – community members can't report bugs
- │  × Currently unlicensed – unsuitable for production use
- │
- │  Our full analysis:
- │
- │  https://squidfunk.github.io/mkdocs-material/blog/2026/02/18/mkdocs-2.0/
-
-INFO    -  Cleaning site directory
-INFO    -  Building documentation to directory: /home/emil/Desktop/.worktrees/Faset_Engine-p3-lighting/build/manual
-INFO    -  Documentation built in 0.84 seconds

examples/renderer/p3_lighting_benchmark.cpp

@@ -1,272 +0,0 @@
-#include <faset/core/io.hpp>
-#include <faset/render/renderer.hpp>
-
-#include <algorithm>
-#include <array>
-#include <cstdint>
-#include <cstdlib>
-#include <filesystem>
-#include <fstream>
-#include <iomanip>
-#include <iostream>
-#include <stdexcept>
-#include <string>
-#include <string_view>
-
-using namespace faset::render;
-namespace fs = std::filesystem;
-
-namespace {
-struct Options {
-    unsigned lights{}, width{1920}, height{1080}, warmup{10}, frames{30}, run_index{};
-    bool shadows{}, validation{}, tile_diagnostics{};
-    VisibilityMode visibility{VisibilityMode::Direct};
-    LightingMode lighting{LightingMode::Auto};
-    std::string light_layout{"dense"};
-    std::string commit{"unknown"}, driver{"unknown"};
-    fs::path csv, capture;
-};
-
-unsigned number(std::string_view text, std::string_view name) {
-    std::size_t end{};
-    const auto value = std::stoul(std::string(text), &end);
-    if (end != text.size() || value > 100000)
-        throw std::invalid_argument("Invalid value for " + std::string(name));
-    return static_cast<unsigned>(value);
-}
-
-Options parse(int argc, char** argv) {
-    Options options;
-    for (int i = 1; i < argc; ++i) {
-        const std::string name = argv[i];
-        if (name == "--list-runs") {
-            std::cout << "{\"lights\":[0,4,16,32,64,128],"
-                         "\"visibility\":[\"direct\",\"gpu-frustum\",\"gpu-occlusion\"],"
-                         "\"shadows\":[\"off\",\"on\"]}\n";
-            std::exit(0);
-        }
-        if (name == "--help") {
-            std::cout << "Usage: faset_p3_lighting_benchmark --lights 0|4|16|32|64|128 "
-                         "--shadows on|off --visibility direct|gpu-frustum|gpu-occlusion "
-                         "--csv PATH [--width N --height N --warmup N --frames N "
-                         "--run-index N --commit SHA --driver NAME --validation on|off "
-                         "--lighting auto|forward|tiled --light-layout dense|localized "
-                         "--tile-diagnostics on|off "
-                         "--capture PATH]\n";
-            std::exit(0);
-        }
-        if (i + 1 >= argc)
-            throw std::invalid_argument("Missing value for " + name);
-        const std::string value = argv[++i];
-        if (name == "--lights") options.lights = number(value, name);
-        else if (name == "--width") options.width = number(value, name);
-        else if (name == "--height") options.height = number(value, name);
-        else if (name == "--warmup") options.warmup = number(value, name);
-        else if (name == "--frames") options.frames = number(value, name);
-        else if (name == "--run-index") options.run_index = number(value, name);
-        else if (name == "--commit") options.commit = value;
-        else if (name == "--driver") options.driver = value;
-        else if (name == "--csv") options.csv = faset::path_from_utf8(value);
-        else if (name == "--capture") options.capture = faset::path_from_utf8(value);
-        else if (name == "--shadows") {
-            if (value != "on" && value != "off")
-                throw std::invalid_argument("--shadows must be on or off");
-            options.shadows = value == "on";
-        } else if (name == "--validation") {
-            if (value != "on" && value != "off")
-                throw std::invalid_argument("--validation must be on or off");
-            options.validation = value == "on";
-        } else if (name == "--tile-diagnostics") {
-            if (value != "on" && value != "off")
-                throw std::invalid_argument("--tile-diagnostics must be on or off");
-            options.tile_diagnostics = value == "on";
-        } else if (name == "--visibility") {
-            if (value == "direct") options.visibility = VisibilityMode::Direct;
-            else if (value == "gpu-frustum") options.visibility = VisibilityMode::GpuFrustum;
-            else if (value == "gpu-occlusion") options.visibility = VisibilityMode::GpuOcclusion;
-            else throw std::invalid_argument("Unknown visibility mode: " + value);
-        } else if (name == "--lighting") {
-            if (value == "auto") options.lighting = LightingMode::Auto;
-            else if (value == "forward") options.lighting = LightingMode::Forward;
-            else if (value == "tiled") options.lighting = LightingMode::Tiled;
-            else throw std::invalid_argument("Unknown lighting mode: " + value);
-        } else if (name == "--light-layout") {
-            if (value != "dense" && value != "localized")
-                throw std::invalid_argument("--light-layout must be dense or localized");
-            options.light_layout = value;
-        } else throw std::invalid_argument("Unknown option: " + name);
-    }
-    constexpr std::array allowed_lights{0u, 4u, 16u, 32u, 64u, 128u};
-    if (options.csv.empty() || options.width == 0 || options.height == 0 ||
-        options.frames == 0 || options.warmup > 1000 ||
-        std::find(allowed_lights.begin(), allowed_lights.end(), options.lights) ==
-            allowed_lights.end())
-        throw std::invalid_argument("Invalid benchmark configuration");
-    return options;
-}
-
-const char* mode_name(VisibilityMode mode) {
-    switch (mode) {
-    case VisibilityMode::Direct: return "direct";
-    case VisibilityMode::GpuFrustum: return "gpu-frustum";
-    case VisibilityMode::GpuOcclusion: return "gpu-occlusion";
-    }
-    return "unknown";
-}
-
-void csv_text(std::ostream& out, std::string_view value) {
-    out << '"';
-    for (const char c : value) {
-        if (c == '"') out << '"';
-        out << c;
-    }
-    out << '"';
-}
-
-Snapshot benchmark_scene(const Options& options) {
-    Snapshot scene;
-    scene.view_id = "p3-lighting-benchmark-fixed-scene";
-    scene.eye = {0, 0, 9};
-    scene.projection = perspective(.9f, float(options.width) / float(options.height), .1f, 100);
-    const auto view = look_at(scene.eye, {0, 0, 0});
-    scene.view_projection = multiply(scene.projection, view);
-    scene.camera_frustum = CameraFrustum{view, scene.projection, .1f, 100, true};
-    scene.authored_lights_present = true;
-    scene.clear_color = {.035f, .04f, .05f, 1};
-    DrawItem receiver;
-    receiver.mesh = cube_mesh();
-    receiver.model = transform({0, 0, -.15f}, {}, {10, 7.5f, .2f});
-    receiver.color = {.65f, .67f, .7f, 1};
-    receiver.roughness = .65f;
-    receiver.cast_shadow = options.shadows;
-    receiver.instance_key = "large-receiver";
-    scene.draws.push_back(receiver);
-    for (int i = 0; i < 9; ++i) {
-        DrawItem object;
-        object.mesh = cube_mesh();
-        object.model = transform({(float(i % 3) - 1.f) * 2.5f,
-                                  (float(i / 3) - 1.f) * 1.8f, .45f},
-                                 {}, {.42f, .42f, .6f});
-        object.color = {.6f + .1f * float(i % 3), .5f, .4f + .1f * float(i / 3), 1};
-        object.cast_shadow = options.shadows;
-        object.instance_key = "caster-" + std::to_string(i);
-        scene.draws.push_back(std::move(object));
-    }
-    for (unsigned i = 0; i < options.lights; ++i) {
-        LocalLight light;
-        light.kind = LocalLight::Kind::Point;
-        light.stable_id = "benchmark-light-" + std::to_string(i);
-        light.position = {(float(i % 8) - 3.5f) * 1.35f,
-                          (float((i / 8) % 8) - 3.5f) * .95f,
-                          2.f + .35f * float(i % 3)};
-        light.color = {.6f + .4f * float(i % 3 == 0),
-                       .6f + .4f * float(i % 3 == 1),
-                       .6f + .4f * float(i % 3 == 2), 1};
-        light.intensity = 5.f;
-        light.range = options.light_layout == "localized" ? 1.75f : 8.f;
-        light.casts_shadow = options.shadows;
-        scene.local_lights.push_back(std::move(light));
-    }
-    return scene;
-}
-
-void benchmark(const Options& options) {
-    RendererConfig config;
-    config.width = options.width;
-    config.height = options.height;
-    config.headless = true;
-    config.validation = options.validation;
-    config.visibility_mode = options.visibility;
-    config.lighting_mode = options.lighting;
-    config.visibility_diagnostics = options.tile_diagnostics;
-    auto renderer = Renderer(config);
-    const auto scene = benchmark_scene(options);
-    for (unsigned i = 0; i < options.warmup; ++i)
-        renderer.render(scene);
-    if (!options.csv.parent_path().empty())
-        fs::create_directories(faset::native_io_path(options.csv.parent_path()));
-    std::ofstream csv(faset::native_io_path(options.csv));
-    if (!csv)
-        throw std::runtime_error("Cannot open benchmark CSV: " + faset::path_to_utf8(options.csv));
-    csv << "light_count,light_layout,shadows,visibility,effective_visibility,lighting_path,"
-           "requested_lighting,"
-           "build_configuration,run_index,frame,"
-           "device,driver,commit,width,height,validation_enabled,validation_errors,"
-           "submitted_local_lights,omitted_local_lights,"
-           "requested_local_shadow_faces,rendered_local_shadow_faces,dropped_shadow_faces,"
-           "shadow_atlas_full_drops,shadow_tiles,draw_calls,gpu_bytes,"
-           "gpu_main_raster_ms,gpu_post_raster_ms,gpu_post_visible,visibility_counters_valid,"
-           "gpu_sun_shadow_ms,gpu_local_shadow_ms,gpu_shadow_ms,gpu_light_tiles_ms,"
-           "gpu_build_plus_raster_ms,light_tile_count,light_tile_counts_valid,"
-           "light_tile_candidate_count,light_tile_overflow_count,"
-           "gpu_ms,cpu_ms,readback_cpu_ms\n";
-    csv << std::fixed << std::setprecision(6);
-    for (unsigned frame = 0; frame < options.frames; ++frame) {
-        renderer.render(scene);
-        const auto stats = renderer.stats();
-        if (stats.validation_errors != 0)
-            throw std::runtime_error("Vulkan validation error during benchmark");
-        if (stats.submitted_local_lights != options.lights || stats.omitted_local_lights != 0)
-            throw std::runtime_error("Renderer did not submit every requested local light");
-        if (stats.effective_visibility_mode != options.visibility)
-            throw std::runtime_error("Requested visibility path fell back during benchmark");
-        if (stats.gpu_main_raster_ms <= 0 || stats.gpu_ms <= 0)
-            throw std::runtime_error("GPU raster or frame timestamp was unavailable");
-        csv << options.lights << ',' << options.light_layout << ','
-            << (options.shadows ? "on" : "off") << ','
-            << mode_name(options.visibility) << ',' << mode_name(stats.effective_visibility_mode)
-            << ',' << stats.effective_lighting_path << ','
-            << (options.lighting == LightingMode::Forward ? "forward" :
-                options.lighting == LightingMode::Tiled ? "tiled" : "auto") << ','
-            << FASET_BENCHMARK_CONFIGURATION << ','
-            << options.run_index << ',' << frame << ',';
-        csv_text(csv, stats.device);
-        csv << ',';
-        csv_text(csv, options.driver);
-        csv << ',';
-        csv_text(csv, options.commit);
-        csv << ',' << options.width << ',' << options.height << ','
-            << (stats.validation_enabled ? 1 : 0) << ',' << stats.validation_errors << ','
-            << stats.submitted_local_lights << ',' << stats.omitted_local_lights << ','
-            << stats.requested_local_shadow_faces << ',' << stats.local_shadow_faces << ','
-            << stats.dropped_shadow_faces << ',' << stats.shadow_atlas_full_drops << ','
-            << stats.local_shadow_tiles << ',' << stats.draw_calls << ','
-            << stats.gpu_allocated_bytes << ','
-            << stats.gpu_main_raster_ms << ',' << stats.gpu_post_raster_ms << ','
-            << stats.gpu_post_visible << ',' << (stats.visibility_counters_valid ? 1 : 0)
-            << ',' << stats.gpu_sun_shadow_ms << ',' << stats.gpu_local_shadow_ms << ','
-            << (stats.gpu_sun_shadow_ms + stats.gpu_local_shadow_ms) << ','
-            << stats.gpu_light_tiles_ms << ','
-            << (stats.gpu_main_raster_ms + stats.gpu_post_raster_ms +
-                stats.gpu_light_tiles_ms) << ','
-            << stats.light_tile_count << ',' << (stats.light_tile_counts_valid ? 1 : 0)
-            << ',' << stats.light_tile_candidate_count << ','
-            << stats.light_tile_overflow_count << ',' << stats.gpu_ms << ','
-            << stats.cpu_ms << ',' << stats.readback_cpu_ms << '\n';
-    }
-    if (!csv)
-        throw std::runtime_error("Cannot finish benchmark CSV: " + faset::path_to_utf8(options.csv));
-    if (!options.capture.empty())
-        renderer.capture(faset::native_io_path(options.capture));
-}
-} // namespace
-
-int benchmark_main(int argc, char** argv) {
-    try {
-        benchmark(parse(argc, argv));
-        return 0;
-    } catch (const std::exception& error) {
-        std::cerr << "P3 lighting benchmark: " << error.what() << '\n';
-        return 1;
-    }
-}
-
-#ifdef _WIN32
-int wmain(int argc, wchar_t** argv) {
-    return faset::run_utf8_main(argc, argv, benchmark_main);
-}
-#else
-int main(int argc, char** argv) {
-    return benchmark_main(argc, argv);
-}
-#endif

include/faset/authoring/service.hpp

@@ -25,7 +25,8 @@ class AuthoringService {
                   const Json& operations, const std::string& idempotency_key = "");
     Json undo(const std::string& document, std::uint64_t expected_revision);
     Json redo(const std::string& document, std::uint64_t expected_revision);
-    Json save(const std::string& document, const std::filesystem::path& relative = {});
+    Json save(const std::string& document, const std::filesystem::path& relative = {},
+              std::optional<std::uint64_t> expected_revision = std::nullopt);
     Json recovery_documents() const;
     Json recover(const std::string& document,
                  std::optional<std::uint64_t> expected_revision = std::nullopt);

include/faset/editor/autosave.hpp

@@ -0,0 +1,35 @@
+#pragma once
+
+#include <faset/core/json.hpp>
+#include <chrono>
+#include <functional>
+#include <map>
+#include <mutex>
+#include <string>
+
+namespace faset::editor {
+
+class AutosaveController {
+  public:
+    using Clock = std::chrono::steady_clock;
+    using SaveFn = std::function<Json(const std::string&, std::uint64_t)>;
+    explicit AutosaveController(SaveFn save);
+
+    // Called from the Editor event loop with an injected monotonic clock for
+    // deterministic tests. Only a named dirty scene becomes eligible to save.
+    void observe(const Json& documents, Clock::time_point now, bool enabled);
+    Json status() const;
+
+  private:
+    struct Entry {
+        std::uint64_t revision{};
+        std::string path, state = "saved", error;
+        Clock::time_point deadline{};
+    };
+    SaveFn save_;
+    mutable std::mutex mutex_;
+    std::map<std::string, Entry> entries_;
+    bool enabled_ = true;
+};
+
+} // namespace faset::editor

include/faset/editor/build_cache.hpp

@@ -0,0 +1,52 @@
+#pragma once
+
+#include <faset/editor/build_service.hpp>
+#include <faset/scripting/project.hpp>
+#include <filesystem>
+#include <optional>
+#include <string>
+
+namespace faset::editor {
+
+struct BuildInputs {
+    std::string source_hash;
+    std::string recipe_hash;
+    std::string toolchain_hash;
+    std::string fingerprint() const;
+};
+
+// Hash all files in Scripts and the active Lua declaration, not only the two
+// conventional gameplay files. Both Editor stale-state and builds use this key.
+std::string gameplay_source_hash(const std::filesystem::path& project_root,
+                                 const scripting::LuaProject& lua);
+BuildInputs capture_build_inputs(const BuildConfig& config, const scripting::LuaProject& lua);
+std::optional<std::string> configured_cmake_value(const BuildConfig& config,
+                                                   std::string_view key);
+
+// Copy a content-addressed, immutable Scripts tree for the native compiler.
+// Returning the same path for equal source bytes preserves Ninja incrementality.
+std::filesystem::path stage_gameplay_sources(const BuildConfig& config,
+                                              const BuildInputs& inputs,
+                                              const scripting::LuaProject& lua,
+                                              std::string_view job_id);
+
+// A compiler replaced at the same path may be invisible to Ninja. Invalidate
+// only this generated native tree; published build generations stay intact.
+void ensure_native_toolchain_stamp(const BuildConfig& config,
+                                   const std::filesystem::path& native_directory,
+                                   const BuildInputs& inputs);
+
+// Native build completes before package reuse is considered. Hash the actual
+// generated outputs, not their timestamps or just the gameplay sources.
+std::string build_package_key(const BuildInputs& inputs,
+                              const std::filesystem::path& native_directory,
+                              const std::string& configuration,
+                              const std::filesystem::path& player,
+                              const std::filesystem::path& exporter);
+
+// A hit is accepted only if the complete published file set and schema match
+// the manifest. Malformed or old manifests are safe cache misses.
+bool validate_build_generation(const std::filesystem::path& directory,
+                               const std::string& package_key);
+
+} // namespace faset::editor

include/faset/editor/build_diagnostics.hpp

@@ -0,0 +1,15 @@
+#pragma once
+
+#include <faset/core/json.hpp>
+#include <filesystem>
+#include <string_view>
+
+namespace faset::editor {
+
+// Parse compiler, MSVC/clang-cl and Lua output into bounded Editor-facing rows.
+// Only sources under the current project's Scripts directory receive a file
+// key, so clients cannot offer navigation to unrelated filesystem paths.
+Json parse_build_diagnostics(std::string_view raw_log, std::string_view phase,
+                             const std::filesystem::path& project_root);
+
+} // namespace faset::editor

include/faset/editor/build_service.hpp

@@ -3,6 +3,7 @@
 #include <filesystem>
 #include <memory>
 #include <string>
+#include <string_view>
 #include <vector>
 
 namespace faset::editor {
@@ -22,6 +23,7 @@ struct JobStatus {
     std::string id, kind, state{"queued"}, stage{"queued"};
     double progress{};
     std::string log, error;
+    Json diagnostics = Json::array();
     Json result = Json::object();
     bool finished() const {
         return state == "succeeded" || state == "failed" || state == "cancelled";
@@ -37,6 +39,9 @@ class BuildService {
     BuildService(const BuildService&) = delete;
     BuildService& operator=(const BuildService&) = delete;
     void scaffold(const std::string& name, int dimension);
+    // Explicit starter choice creates a runnable start scene. The legacy overload above
+    // remains intentionally scene-free for existing command-line and API callers.
+    void scaffold(const std::string& name, int dimension, std::string_view language);
     std::string start_build();
     std::string start_cook(Json resolved_scene);
     // Publishes output/generations/<id>; current.json changes only after all validation succeeds.

include/faset/editor/project_launcher.hpp

@@ -8,6 +8,7 @@ struct ProjectSelection {
     std::string name;
     int dimension = 3;
     bool create = false;
+    std::string language = "cpp";
 };
 // Records only existing, valid projects. Call after successful Session setup.
 void remember_project(const std::filesystem::path& project);
@@ -15,7 +16,9 @@ class ProjectLauncher {
   public:
     ProjectLauncher(render::Renderer&, const std::filesystem::path& engine_root,
                     const std::filesystem::path& initial_project = {},
-                    const std::filesystem::path& recent_store = {});
+                    const std::filesystem::path& recent_store = {},
+                    const std::optional<ProjectSelection>& retry = {},
+                    std::string creation_error = {});
     ~ProjectLauncher();
     void frame(const std::vector<render::Event>&);
     const render::Snapshot& snapshot() const;
@@ -30,5 +33,7 @@ class ProjectLauncher {
 std::optional<ProjectSelection>
 run_project_launcher(const std::filesystem::path& engine_root,
                      const std::filesystem::path& initial_project = {},
-                     std::uint64_t max_frames = 0, const std::filesystem::path& capture = {});
+                     std::uint64_t max_frames = 0, const std::filesystem::path& capture = {},
+                     const std::optional<ProjectSelection>& retry = {},
+                     std::string creation_error = {});
 } // namespace faset::editor

include/faset/editor/session.hpp

@@ -2,10 +2,12 @@
 #include <faset/assets/asset_pipeline.hpp>
 #include <faset/core/process.hpp>
 #include <faset/editor/build_service.hpp>
+#include <faset/editor/autosave.hpp>
 #include <faset/editor/commands.hpp>
 #include <faset/editor/plugins.hpp>
 #include <memory>
 #include <mutex>
+#include <string_view>
 #include <thread>
 
 namespace faset::editor {
@@ -33,6 +35,7 @@ class Session {
         return plugins_ ? plugins_->panels() : Json::array();
     }
     void scaffold(const std::string& name, int dimension);
+    void scaffold(const std::string& name, int dimension, std::string_view language);
     const SessionConfig& config() const {
         return config_;
     }
@@ -60,6 +63,8 @@ class Session {
     Commands commands_;
     assets::AssetPipeline assets_;
     BuildService builds_;
+    AutosaveController autosave_;
+    bool autosave_enabled_ = true;
     std::map<std::string, std::shared_ptr<ImportTask>> imports_;
     std::vector<std::jthread> workers_;
     std::vector<std::string> logs_;

include/faset/render/lighting.hpp

@@ -1,76 +0,0 @@
-#pragma once
-#include <faset/render/visibility.hpp>
-#include <cstddef>
-#include <cstdint>
-#include <span>
-#include <string>
-#include <vector>
-
-namespace faset::render {
-
-enum class ShadowDropReason { None, Unavailable, TileBudget, CasterBudget };
-enum class ShadowRedrawReason { EveryFrame };
-
-struct ShadowBudget {
-    std::uint32_t max_sun_views{4};
-    std::uint32_t max_local_faces{16};
-    std::uint32_t max_caster_draws{4096};
-    std::uint32_t max_local_lights{128};
-    std::uint32_t sun_atlas_size{2048};
-    std::uint32_t local_atlas_size{2048};
-    float max_shadow_distance{80};
-    bool sun_atlas_available{true};
-    bool local_atlas_available{true};
-};
-
-struct ShadowCasterBounds {
-    Bounds world;
-    std::uint32_t draw_index{}; // Index of the original source LOD-0 DrawItem.
-};
-
-struct ShadowView {
-    enum class Kind { Sun, Spot, Point };
-    Kind kind{Kind::Sun};
-    std::string light_id;
-    std::uint32_t face_index{};
-    std::uint32_t tile_index{};
-    std::uint32_t tile_origin_x{}, tile_origin_y{}, tile_size{}, usable_size{};
-    Mat4 view_projection{identity};
-    std::array<float, 4> atlas_scale_offset{};
-    std::array<float, 4> guarded_clamp{};
-    float split_near{}, split_far{};
-    float snapped_center_x{}, snapped_center_y{};
-    std::vector<std::uint32_t> caster_indices;
-    bool valid{};
-    ShadowDropReason reason{ShadowDropReason::None};
-    ShadowRedrawReason redraw_reason{ShadowRedrawReason::EveryFrame};
-};
-
-struct LocalShadowAssignment {
-    std::size_t source_index{};
-    std::uint32_t first_view{};
-    std::uint32_t face_count{};
-    bool valid{};
-    ShadowDropReason reason{ShadowDropReason::None};
-};
-
-struct ShadowPlan {
-    std::vector<ShadowView> sun_views; // Requested slots, including explicitly invalid ones.
-    std::vector<ShadowView> local_views; // Only complete, valid spot/point allocations.
-    std::vector<std::size_t> submitted_local_indices; // Priority/influence/stable-ID order.
-    std::vector<LocalShadowAssignment> local_assignments;
-    std::uint32_t requested_sun_cascades{}, effective_sun_cascades{};
-    std::uint32_t local_faces_requested{}, local_faces_used{};
-    std::uint32_t dropped_sun_views{}, dropped_local_faces{}, dropped_point_faces{};
-    std::uint32_t omitted_local_lights{}, caster_draws{};
-    std::uint32_t sun_atlas_size{}, local_atlas_size{};
-};
-
-// Stateless: every scheduled tile is cleared/redrawn; no prior-frame depth or
-// ownership is reused. Shadow casters are source LOD-0 world bounds, independent
-// of the camera/P2 visibility decision. This function performs no Vulkan work.
-ShadowPlan build_shadow_plan(const Snapshot& frame,
-                             std::span<const ShadowCasterBounds> casters,
-                             const ShadowBudget& budget = {});
-
-} // namespace faset::render

include/faset/render/renderer.hpp

@@ -80,34 +80,6 @@ struct Text {
     Color color{0.85f, 0.87f, 0.90f, 1};
     float size{14};
 };
-struct SunLight {
-    std::string stable_id;
-    Vec3 direction{-0.5f, -1, -0.3f};
-    Color color{1, 1, 1, 1};
-    float intensity{1};
-    bool casts_shadow{true};
-};
-struct LocalLight {
-    enum class Kind { Point, Spot };
-    Kind kind{Kind::Point};
-    std::string stable_id;
-    Vec3 position{};
-    Vec3 direction{0, 0, -1};
-    Color color{1, 1, 1, 1};
-    float intensity{1};
-    float range{10};
-    float inner_angle{0.35f};
-    float outer_angle{0.7f};
-    bool casts_shadow{true};
-    int shadow_priority{};
-};
-struct CameraFrustum {
-    Mat4 view{identity};
-    Mat4 projection{identity};
-    float near_plane{0.1f};
-    float far_plane{1000};
-    bool perspective{true};
-};
 struct Snapshot {
     // Optional scene viewport in drawable pixels (x, y, width, height); zero size uses the full
     // target.
@@ -128,15 +100,8 @@ struct Snapshot {
     // Distinguishes temporal histories when one Renderer displays different views.
     std::string view_id{};
     bool camera_cut{};
-    // Empty legacy scenes may use the renderer's compatibility sun. Any authored light
-    // component, including an explicitly disabled or opaque future one, suppresses it.
-    bool authored_lights_present{};
-    std::optional<SunLight> sun{};
-    std::vector<LocalLight> local_lights;
-    std::optional<CameraFrustum> camera_frustum{};
 };
 enum class VisibilityMode { Direct, GpuFrustum, GpuOcclusion };
-enum class LightingMode { Auto, Forward, Tiled };
 // CPU-only validation used before publishing a game or creating Vulkan pipelines.
 void validate_shader_bundle(const std::filesystem::path& directory);
 void validate_gpu_shader_bundle(const std::filesystem::path& directory);
@@ -147,9 +112,6 @@ struct RendererConfig {
     bool headless{false};
     bool validation{true};
     VisibilityMode visibility_mode{VisibilityMode::Direct};
-    // Auto prefers the 16x16 tiled light list at 32+ submitted local lights.
-    // Forward remains the reference and the fallback on unsupported devices.
-    LightingMode lighting_mode{LightingMode::Auto};
     // GPU counter readback is diagnostic-only; normal visibility uses no CPU feedback.
     bool visibility_diagnostics{false};
     // Optional isolated shader bundle, useful for editor preview and shader reload tests.
@@ -187,15 +149,6 @@ struct FrameStats {
     std::uint64_t gpu_allocated_bytes{};
     std::uint32_t texture_count{};
     std::uint32_t vertices{}, draw_calls{}, culled_meshes{}, validation_errors{};
-    std::uint32_t submitted_local_lights{}, omitted_local_lights{};
-    std::uint32_t requested_sun_cascades{}, effective_sun_cascades{};
-    std::uint32_t sun_shadow_caster_draws{};
-    std::uint64_t sun_shadow_atlas_bytes{};
-    std::uint32_t requested_local_shadow_faces{}, local_shadow_faces{}, local_shadow_tiles{};
-    std::uint32_t dropped_shadow_faces{}, dropped_point_shadow_faces{};
-    std::uint32_t shadow_atlas_full_drops{}, shadow_caster_budget_drops{};
-    std::uint32_t shadow_unavailable_drops{}, shadow_caster_draws{};
-    std::uint64_t local_shadow_atlas_bytes{};
     bool gpu_visibility_active{}, hzb_valid{};
     // Requested and actual paths for the last frame; actual may be less capable.
     VisibilityMode requested_visibility_mode{VisibilityMode::Direct};
@@ -207,13 +160,6 @@ struct FrameStats {
     double cpu_ms{}, gpu_ms{}, readback_cpu_ms{};
     double gpu_main_cull_ms{}, gpu_main_raster_ms{}, gpu_hzb_ms{};
     double gpu_post_cull_ms{}, gpu_post_raster_ms{};
-    double gpu_sun_shadow_ms{}, gpu_local_shadow_ms{};
-    double gpu_light_tiles_ms{};
-    std::uint32_t light_tile_count{};
-    // Optional tile-list readback, valid only when visibility diagnostics are on.
-    bool light_tile_counts_valid{};
-    std::uint32_t light_tile_candidate_count{}, light_tile_overflow_count{};
-    std::string effective_lighting_path{"forward"};
     std::string device;
 };
 struct HzbDebugImage {

mkdocs.yml

@@ -44,7 +44,6 @@ nav:
       - Editor workspace: editor/workspace.md
       - Scene templates: editor/templates.md
       - Assets and Blender: editor/assets.md
-      - Lighting: editor/lighting.md
       - GPU visibility and mesh LOD: editor/visibility-lod.md
       - Build, Play, and export: editor/export.md
       - Profiling and measurements: editor/profiling.md

shaders/baseline.slang

@@ -24,35 +24,6 @@ struct FrameParameters {
 [[vk::binding(1,0)]] SamplerState shadowSampler;
 [[vk::binding(2,0)]] Texture2D<float4> colorMap;
 [[vk::binding(3,0)]] SamplerState colorSampler;
-// Shared Direct/P2 graphics ABI. The legacy material set remains set 0;
-// GPU-only instance/visibility records occupy set 2.
-struct LightingHeader {
-    uint4 counts;                    // local count, sun enabled, sun shadow enabled, sun view count
-    float4 sunDirectionIntensity;    // xyz world-space ray direction, w intensity
-    float4 sunColor;
-    float4 cameraForwardShadowDistance;
-    float4 cascadeSplits;
-};
-struct LocalLightGpu {
-    float4 positionRange;
-    float4 directionCosOuter;
-    float4 colorIntensity;
-    float4 coneTypeShadowView;       // cos(inner), 0=point/1=spot, shadow view, flags
-    float4 reserved;
-};
-struct ShadowViewGpu {
-    column_major float4x4 viewProjection;
-    float4 tileScaleOffset;
-    float4 guardedClamp;
-    float4 biasFlags;
-};
-[[vk::binding(0,1)]] StructuredBuffer<LightingHeader> lightingFrame;
-[[vk::binding(1,1)]] StructuredBuffer<LocalLightGpu> localLights;
-[[vk::binding(2,1)]] StructuredBuffer<ShadowViewGpu> shadowViews;
-[[vk::binding(3,1)]] Texture2D<float> localShadowAtlas;
-// 4-word header, then 66 words per 16x16 tile: count, overflow, 64 indices.
-// An overflowing tile evaluates the full submitted list instead of losing light.
-[[vk::binding(4,1)]] StructuredBuffer<uint> lightTileWords;
 [shader("vertex")]
 VertexOutput vertexMain(VertexInput v) {
     VertexOutput o;
@@ -61,70 +32,6 @@ VertexOutput vertexMain(VertexInput v) {
 }
 [shader("vertex")]
 float4 shadowMain(VertexInput v) : SV_Position { return mul(frame.lightViewProjection, float4(v.world,1)); }
-float sampleSunCascade(uint index, float3 world, float nl) {
-    ShadowViewGpu record = shadowViews[index];
-    if (record.biasFlags.w < 0.5) return 1.0;
-    float4 clip = mul(record.viewProjection, float4(world,1));
-    if (clip.w <= 0.0) return 1.0;
-    float3 projected = clip.xyz / clip.w;
-    float2 localUV = projected.xy * 0.5 + 0.5;
-    if (any(localUV < 0.0) || any(localUV > 1.0) ||
-        projected.z < 0.0 || projected.z > 1.0) return 1.0;
-    float2 atlasUV = localUV * record.tileScaleOffset.xy + record.tileScaleOffset.zw;
-    float bias = max(record.biasFlags.x, record.biasFlags.y * (1.0 - nl));
-    float visible = 0.0;
-    for (int y=-1; y<=1; ++y) for (int x=-1; x<=1; ++x) {
-        float2 tap = clamp(atlasUV + float2(x,y) * record.biasFlags.z,
-                           record.guardedClamp.xy, record.guardedClamp.zw);
-        float depth = shadowMap.SampleLevel(shadowSampler, tap, 0);
-        visible += projected.z - bias <= depth ? 1.0 / 9.0 : 0.0;
-    }
-    return visible;
-}
-float sampleLocalFace(uint index, float3 world, float nl) {
-    ShadowViewGpu record = shadowViews[index];
-    if (record.biasFlags.w < 0.5) return 1.0;
-    float4 clip = mul(record.viewProjection, float4(world,1));
-    if (clip.w <= 0.0) return 1.0;
-    float3 projected = clip.xyz / clip.w;
-    float2 localUV = projected.xy * 0.5 + 0.5;
-    if (any(localUV < 0.0) || any(localUV > 1.0) ||
-        projected.z < 0.0 || projected.z > 1.0) return 1.0;
-    float2 atlasUV = localUV * record.tileScaleOffset.xy + record.tileScaleOffset.zw;
-    float bias = max(record.biasFlags.x, record.biasFlags.y * (1.0 - nl));
-    float visible = 0.0;
-    for (int y=-1; y<=1; ++y) for (int x=-1; x<=1; ++x) {
-        float2 tap = clamp(atlasUV + float2(x,y) * record.biasFlags.z,
-                           record.guardedClamp.xy, record.guardedClamp.zw);
-        float depth = localShadowAtlas.SampleLevel(shadowSampler, tap, 0);
-        visible += projected.z - bias <= depth ? 1.0 / 9.0 : 0.0;
-    }
-    return visible;
-}
-uint pointShadowFace(float3 lightToFragment) {
-    float3 magnitude = abs(lightToFragment);
-    if (magnitude.x >= magnitude.y && magnitude.x >= magnitude.z)
-        return lightToFragment.x >= 0.0 ? 0 : 1;
-    if (magnitude.y >= magnitude.z)
-        return lightToFragment.y >= 0.0 ? 2 : 3;
-    return lightToFragment.z >= 0.0 ? 4 : 5;
-}
-float3 directBRDF(float3 base, float rough, float metal, float3 n, float3 view, float3 l) {
-    const float pi = 3.14159265;
-    float nl = max(dot(n,l),0.0);
-    if (nl <= 0.0) return float3(0);
-    float3 halfVector = l + view;
-    float halfLengthSquared = dot(halfVector, halfVector);
-    float3 h = halfLengthSquared > 1e-8 ? halfVector * rsqrt(halfLengthSquared) : n;
-    float nv=max(dot(n,view),0.001), nh=max(dot(n,h),0.0), vh=max(dot(view,h),0.0);
-    float a=rough*rough, a2=a*a, denom=nh*nh*(a2-1.0)+1.0;
-    float d=a2/(pi*denom*denom+0.0001);
-    float k=(rough+1.0)*(rough+1.0)/8.0;
-    float g=(nl/(nl*(1.0-k)+k))*(nv/(nv*(1.0-k)+k));
-    float3 f0=lerp(float3(0.04),base,metal), fresnel=f0+(1.0-f0)*pow(1.0-vh,5.0);
-    float3 spec=d*g*fresnel/max(4.0*nv*nl,0.001);
-    return ((1.0-fresnel)*(1.0-metal)*base/pi+spec)*nl;
-}
 [shader("fragment")]
 float4 fragmentMain(VertexOutput v) : SV_Target {
     float4 sampled = colorMap.Sample(colorSampler, v.uv);
@@ -134,87 +41,28 @@ float4 fragmentMain(VertexOutput v) : SV_Target {
         return v.color * sampled;
     }
     float4 base = v.color * sampled;
-    LightingHeader lighting = lightingFrame[0];
-    float3 n=normalize(v.normal);
-    float3 viewDelta=frame.eye.xyz-v.world;
-    float viewLengthSquared=dot(viewDelta,viewDelta);
-    float3 view=viewLengthSquared > 1e-8 ? viewDelta*rsqrt(viewLengthSquared) : n;
+    const float pi = 3.14159265;
+    float3 n=normalize(v.normal), l=normalize(-frame.lightDirection.xyz), view=normalize(frame.eye.xyz-v.world), h=normalize(l+view);
+    float nl=max(dot(n,l),0.0), nv=max(dot(n,view),0.001), nh=max(dot(n,h),0.0), vh=max(dot(view,h),0.0);
     float rough=clamp(v.material.x,0.08,1.0), metal=saturate(v.material.y);
-    float3 linear=base.rgb*.12;
-    if (lighting.counts.y != 0 && lighting.sunDirectionIntensity.w > 0) {
-        float3 l=normalize(-lighting.sunDirectionIntensity.xyz);
-        float nl=max(dot(n,l),0.0);
-        float visibility=1.0;
-        if (lighting.counts.z != 0 && lighting.counts.w != 0 && nl > 0) {
-            if (lighting.counts.w == 1) {
-                visibility = sampleSunCascade(0, v.world, nl);
-            } else {
-                float cameraDepth = dot(v.world - frame.eye.xyz,
-                                        lighting.cameraForwardShadowDistance.xyz);
-                if (cameraDepth >= 0.0 &&
-                    cameraDepth <= lighting.cameraForwardShadowDistance.w) {
-                    uint cascade = 0;
-                    while (cascade + 1 < lighting.counts.w &&
-                           cameraDepth > lighting.cascadeSplits[cascade]) ++cascade;
-                    visibility = sampleSunCascade(cascade, v.world, nl);
-                    if (cascade + 1 < lighting.counts.w) {
-                        float previousSplit = cascade == 0 ? 0.0 :
-                                              lighting.cascadeSplits[cascade-1];
-                        float blendWidth = max(0.2,
-                            0.1 * (lighting.cascadeSplits[cascade] - previousSplit));
-                        float blend = saturate((cameraDepth -
-                            (lighting.cascadeSplits[cascade] - blendWidth)) / blendWidth);
-                        if (blend > 0.0)
-                            visibility = lerp(visibility,
-                                sampleSunCascade(cascade+1, v.world, nl), blend);
-                    }
-                }
-            }
-        }
-        linear += directBRDF(base.rgb, rough, metal, n, view, l) *
-                  lighting.sunColor.rgb * (lighting.sunDirectionIntensity.w * 3.0 * visibility);
-    }
-    uint candidateCount = lighting.counts.x;
-    uint tileBase = 0;
-    bool tileList = false;
-    if (lightTileWords[1] != 0 && lightTileWords[0] != 0 && lightTileWords[2] != 0) {
-        uint tileX = min(uint(v.position.x) / 16u, lightTileWords[0] - 1u);
-        uint tileY = min(uint(v.position.y) / 16u, lightTileWords[2] - 1u);
-        tileBase = 4u + (tileY * lightTileWords[0] + tileX) * 66u;
-        if (lightTileWords[tileBase + 1u] == 0) {
-            candidateCount = min(lightTileWords[tileBase], lighting.counts.x);
-            tileList = true;
+    float a=rough*rough, a2=a*a, denom=nh*nh*(a2-1.0)+1.0;
+    float d=a2/(pi*denom*denom+0.0001);
+    float k=(rough+1.0)*(rough+1.0)/8.0;
+    float g=(nl/(nl*(1.0-k)+k))*(nv/(nv*(1.0-k)+k));
+    float3 f0=lerp(float3(0.04),base.rgb,metal), fresnel=f0+(1.0-f0)*pow(1.0-vh,5.0);
+    float3 spec=d*g*fresnel/max(4.0*nv*nl,0.001);
+    float4 lightClip=mul(frame.lightViewProjection,float4(v.world,1));
+    float3 projected=lightClip.xyz/lightClip.w;
+    float2 uv=projected.xy*.5+.5;
+    float visibility=1.0;
+    if(all(uv>=0.0)&&all(uv<=1.0)&&projected.z>=0.0&&projected.z<=1.0) {
+        visibility=0.0;
+        for(int y=-1;y<=1;++y) for(int x=-1;x<=1;++x) {
+            float depth=shadowMap.SampleLevel(shadowSampler,uv+float2(x,y)/1024.0,0);
+            visibility += projected.z-max(0.0008,0.003*(1.0-nl)) <= depth ? 1.0/9.0 : 0.0;
         }
     }
-    for (uint candidate=0; candidate<candidateCount; ++candidate) {
-        uint i = tileList ? lightTileWords[tileBase + 2u + candidate] : candidate;
-        LocalLightGpu light=localLights[i];
-        float3 delta=light.positionRange.xyz-v.world;
-        float distanceSquared=max(dot(delta,delta),1e-6);
-        float distance=sqrt(distanceSquared);
-        float range=max(light.positionRange.w,1e-4);
-        if (distance >= range || light.colorIntensity.w <= 0) continue;
-        float3 l=delta/distance;
-        float relative=distance/range;
-        float cutoff=1.0-relative*relative*relative*relative;
-        float attenuation=cutoff*cutoff/(1.0+distanceSquared);
-        if (light.coneTypeShadowView.y > 0.5) {
-            float cosAngle=dot(-l,normalize(light.directionCosOuter.xyz));
-            float denominator=max(light.coneTypeShadowView.x-light.directionCosOuter.w,1e-4);
-            float cone=saturate((cosAngle-light.directionCosOuter.w)/denominator);
-            attenuation *= cone*cone*(3.0-2.0*cone);
-        }
-        float visibility = 1.0;
-        float nl = max(dot(n,l), 0.0);
-        if (light.coneTypeShadowView.w > 0.5 && nl > 0.0 && attenuation > 0.0) {
-            uint face = light.coneTypeShadowView.w > 1.5 ?
-                pointShadowFace(v.world - light.positionRange.xyz) : 0;
-            uint viewIndex = uint(light.coneTypeShadowView.z + 0.5) + face;
-            visibility = sampleLocalFace(viewIndex, v.world, nl);
-        }
-        linear += directBRDF(base.rgb, rough, metal, n, view, l) *
-                  light.colorIntensity.rgb * (light.colorIntensity.w * attenuation * visibility);
-    }
+    float3 linear=base.rgb*.12 + ((1.0-fresnel)*(1.0-metal)*base.rgb/pi+spec)*nl*3.0*visibility;
     linear=linear/(1.0+linear);
     return float4(pow(max(linear,0),float3(1.0/2.2)),base.a);
 }

shaders/gpu_scene.slang

@@ -57,9 +57,9 @@ struct GpuFrameParameters {
     uint4 drawInfo; // x=visible ID range base; firstInstance is always zero
 };
 [[vk::push_constant]] ConstantBuffer<GpuFrameParameters> gpuFrame;
-[[vk::binding(0,2)]] StructuredBuffer<InstanceRecord> gfxInstances;
-[[vk::binding(1,2)]] StructuredBuffer<uint> gfxVisibleIds;
-[[vk::binding(2,2)]] StructuredBuffer<ViewRecord> gfxViews;
+[[vk::binding(0,1)]] StructuredBuffer<InstanceRecord> gfxInstances;
+[[vk::binding(1,1)]] StructuredBuffer<uint> gfxVisibleIds;
+[[vk::binding(2,1)]] StructuredBuffer<ViewRecord> gfxViews;
 
 // All indirect commands use firstInstance=0. The raw Vulkan index avoids the
 // BaseInstance read that Slang adds for SV_InstanceID (DrawParameters feature).

shaders/light_tiles.slang

@@ -1,75 +0,0 @@
-// Conservative depth-free 16x16 Forward+ construction. One invocation owns
-// one tile, so indices remain in the same sorted order as the forward reference.
-struct LocalLightGpu {
-    float4 positionRange;
-    float4 directionCosOuter;
-    float4 colorIntensity;
-    float4 coneTypeShadowView;
-    float4 reserved;
-};
-struct TileBuildParameters {
-    column_major float4x4 viewProjection;
-    float4 viewport; // x, y, width, height in framebuffer pixels
-    uint4 dimensions; // tilesX, tilesY, submitted local lights, capacity (<= 64)
-};
-[[vk::push_constant]] ConstantBuffer<TileBuildParameters> build;
-[[vk::binding(0,0)]] StructuredBuffer<LocalLightGpu> localLights;
-[[vk::binding(1,0)]] RWStructuredBuffer<uint> tileWords;
-
-bool sphereTouchesPlane(float3 center, float radius, float4 plane) {
-    // The final epsilon admits boundary/rounding cases rather than dropping a
-    // light. We intentionally do not use scene depth or reject near-plane cuts.
-    return dot(plane, float4(center, 1.0)) + radius * length(plane.xyz) >= -1e-4;
-}
-
-[shader("compute")]
-[numthreads(64, 1, 1)]
-void lightTileMain(uint3 dispatchId : SV_DispatchThreadID) {
-    uint tileId = dispatchId.x;
-    uint tilesX = build.dimensions.x;
-    uint tilesY = build.dimensions.y;
-    if (tileId >= tilesX * tilesY) return;
-    if (tileId == 0) {
-        tileWords[0] = tilesX;
-        tileWords[1] = 1;
-        tileWords[2] = tilesY;
-        tileWords[3] = min(build.dimensions.w, 64u);
-    }
-    uint tileX = tileId % tilesX;
-    uint tileY = tileId / tilesX;
-    float x0 = float(tileX * 16u);
-    float y0 = float(tileY * 16u);
-    float x1 = x0 + 16.0;
-    float y1 = y0 + 16.0;
-    float left = 2.0 * (x0 - build.viewport.x) / build.viewport.z - 1.0;
-    float right = 2.0 * (x1 - build.viewport.x) / build.viewport.z - 1.0;
-    float top = 2.0 * (y0 - build.viewport.y) / build.viewport.w - 1.0;
-    float bottom = 2.0 * (y1 - build.viewport.y) / build.viewport.w - 1.0;
-    float4 xRow = mul(float4(1, 0, 0, 0), build.viewProjection);
-    float4 yRow = mul(float4(0, 1, 0, 0), build.viewProjection);
-    float4 wRow = mul(float4(0, 0, 0, 1), build.viewProjection);
-    float4 leftPlane = xRow - left * wRow;
-    float4 rightPlane = right * wRow - xRow;
-    float4 topPlane = yRow - top * wRow;
-    float4 bottomPlane = bottom * wRow - yRow;
-    uint base = 4u + tileId * 66u;
-    uint count = 0;
-    bool overflow = false;
-    for (uint i = 0; i < build.dimensions.z; ++i) {
-        LocalLightGpu light = localLights[i];
-        if (light.colorIntensity.w <= 0.0) continue;
-        float3 center = light.positionRange.xyz;
-        float radius = light.positionRange.w;
-        if (!sphereTouchesPlane(center, radius, leftPlane) ||
-            !sphereTouchesPlane(center, radius, rightPlane) ||
-            !sphereTouchesPlane(center, radius, topPlane) ||
-            !sphereTouchesPlane(center, radius, bottomPlane)) continue;
-        if (count < min(build.dimensions.w, 64u))
-            tileWords[base + 2u + count] = i;
-        else
-            overflow = true;
-        ++count;
-    }
-    tileWords[base] = min(count, min(build.dimensions.w, 64u));
-    tileWords[base + 1u] = overflow ? 1u : 0u;
-}

src/authoring/schema.cpp

@@ -156,15 +156,6 @@ void SchemaRegistry::validate_component(const Json& component) const {
     for (const auto& [id, value] : component["fields"].items())
         if (metadata["fields"].contains(id))
             validate_field(value, metadata["fields"][id]);
-    if (type == "faset.light") {
-        auto effective = default_fields(type);
-        effective.update(component.at("fields"));
-        if (effective.at("kind") == "spot")
-            require(effective.at("inner_angle").get<double>() <=
-                        effective.at("outer_angle").get<double>(),
-                    "validation.light_cone",
-                    "Spotlight inner_angle must not exceed outer_angle");
-    }
 }
 void SchemaRegistry::add_migration(const std::string& type, int from_version, Json rules) {
     require(contains(type) && from_version > 0 && from_version < schema(type).value("version", 1) &&
@@ -261,25 +252,9 @@ SchemaRegistry builtin_schemas() {
         {{"fov", Json{{"type", "number"}, {"default", 60.0}, {"min", 1.0}, {"max", 179.0}}},
          {"near", Json{{"type", "number"}, {"default", 0.1}, {"min", 0.001}}},
          {"far", Json{{"type", "number"}, {"default", 1000.0}, {"min", 0.01}}}});
-    add("faset.light", "Light",
-        {{"kind", Json{{"type", "string"},
-                        {"default", "directional"},
-                        {"enum", {"directional", "point", "spot"}}}},
-         {"enabled", field("boolean", true)},
-         {"color", field("color", {1, 1, 1, 1})},
-         {"intensity", Json{{"type", "number"}, {"default", 1.0}, {"min", 0.0}}},
-         {"range", Json{{"type", "number"}, {"default", 10.0}, {"min", 0.001}}},
-         {"inner_angle", Json{{"type", "number"},
-                              {"default", 0.35}, {"min", 0.0}, {"max", 1.55},
-                              {"unit", "radians"}}},
-         {"outer_angle", Json{{"type", "number"},
-                              {"default", 0.7}, {"min", 0.001}, {"max", 1.55},
-                              {"unit", "radians"}}},
-         {"casts_shadow", field("boolean", true)},
-         {"shadow_priority", Json{{"type", "integer"},
-                                   {"default", 0},
-                                   {"min", std::numeric_limits<int>::min()},
-                                   {"max", std::numeric_limits<int>::max()}}}});
+    add("faset.light", "Directional Light",
+        {{"color", field("color", {1, 1, 1, 1})},
+         {"intensity", Json{{"type", "number"}, {"default", 1.0}, {"min", 0.0}}}});
     for (int dimension : {2, 3}) {
         Json vector = dimension == 2 ? Json{0, 0} : Json{0, 0, 0};
         Json extents = dimension == 2 ? Json{0.5, 0.5} : Json{0.5, 0.5, 0.5};

src/authoring/service.cpp

@@ -573,9 +573,12 @@ Json AuthoringService::undo(const std::string& id, std::uint64_t revision) {
 Json AuthoringService::redo(const std::string& id, std::uint64_t revision) {
     return history(id, revision, true);
 }
-Json AuthoringService::save(const std::string& id, const std::filesystem::path& relative) {
+Json AuthoringService::save(const std::string& id, const std::filesystem::path& relative,
+                            std::optional<std::uint64_t> expected_revision) {
     std::lock_guard lock(mutex_);
     auto& current = state(id);
+    if (expected_revision)
+        check_revision(current.revision, *expected_revision);
     const auto selected = relative.empty() ? current.path : relative.lexically_normal();
     require(!selected.empty(), "save.path", "Choose a scene path before saving");
     const auto path = project_path(root_, selected);

src/editor/autosave.cpp

@@ -0,0 +1,88 @@
+#include <faset/editor/autosave.hpp>
+
+#include <faset/core/error.hpp>
+#include <set>
+#include <stdexcept>
+
+namespace faset::editor {
+
+AutosaveController::AutosaveController(SaveFn save) : save_(std::move(save)) {
+    if (!save_)
+        throw std::invalid_argument("Autosave requires a save callback");
+}
+
+void AutosaveController::observe(const Json& documents, Clock::time_point now, bool enabled) {
+    std::lock_guard lock(mutex_);
+    enabled_ = enabled;
+    std::set<std::string> present;
+    for (const auto& document : documents) {
+        const auto id = document.at("id").get<std::string>();
+        const auto revision = document.at("revision").get<std::uint64_t>();
+        const auto path = document.value("path", std::string());
+        const auto dirty = document.value("dirty", false);
+        present.insert(id);
+        auto [found, inserted] = entries_.try_emplace(id);
+        auto& entry = found->second;
+        const auto changed = inserted || entry.revision != revision || entry.path != path;
+        const auto prior_state = entry.state;
+        entry.revision = revision;
+        entry.path = path;
+        if (!dirty) {
+            entry.state = "saved";
+            entry.error.clear();
+            continue;
+        }
+        if (path.empty()) {
+            entry.state = "save_as_required";
+            entry.error.clear();
+            continue;
+        }
+        if (!enabled) {
+            entry.state = "disabled";
+            entry.error.clear();
+            continue;
+        }
+        if (changed || prior_state == "disabled" || prior_state == "saved" ||
+            prior_state == "save_as_required") {
+            entry.state = "pending";
+            entry.error.clear();
+            entry.deadline = now + std::chrono::seconds(2);
+        }
+        if (entry.state != "pending" || now < entry.deadline)
+            continue;
+        entry.state = "saving";
+        try {
+            const auto saved = save_(id, revision);
+            if (saved.at("revision").get<std::uint64_t>() != revision ||
+                saved.at("dirty").get<bool>())
+                throw std::runtime_error("Save returned an unexpected document revision");
+            entry.state = "saved";
+            entry.error.clear();
+        } catch (const Error& error) {
+            entry.state = error.code() == "save.disk_conflict" ||
+                                  error.code() == "revision.conflict"
+                              ? "conflict"
+                              : "failed";
+            entry.error = error.what();
+        } catch (const std::exception& error) {
+            entry.state = "failed";
+            entry.error = error.what();
+        }
+    }
+    for (auto it = entries_.begin(); it != entries_.end();)
+        it = present.contains(it->first) ? std::next(it) : entries_.erase(it);
+}
+
+Json AutosaveController::status() const {
+    std::lock_guard lock(mutex_);
+    Json documents = Json::array();
+    for (const auto& [id, entry] : entries_)
+        documents.push_back({{"id", id},
+                             {"state", entry.state},
+                             {"revision", entry.revision},
+                             {"path", entry.path},
+                             {"error", entry.error}});
+    return {{"enabled", enabled_}, {"documents", documents}};
+}
+
+} // namespace faset::editor

src/editor/build_cache.cpp

@@ -0,0 +1,393 @@
+#include <faset/editor/build_cache.hpp>
+
+#include <faset/authoring/schema.hpp>
+#include <faset/core/hash.hpp>
+#include <faset/core/io.hpp>
+#include <faset/core/process.hpp>
+#include <cctype>
+#include <cstdlib>
+#include <set>
+#include <stdexcept>
+
+namespace faset::editor {
+namespace fs = std::filesystem;
+namespace {
+std::string normalized_hash(const Json& value) {
+    return sha256(value.dump());
+}
+std::pair<std::string, std::string> parse_define(const std::string& argument) {
+    if (!argument.starts_with("-D"))
+        throw std::invalid_argument("Gameplay configure arguments must be -DNAME=value options");
+    const auto equal = argument.find('=', 2);
+    if (equal == std::string::npos || equal == 2)
+        throw std::invalid_argument("Invalid gameplay configure definition");
+    const auto colon = argument.find(':', 2);
+    const auto key = argument.substr(2, colon < equal ? colon - 2 : equal - 2);
+    if (key.empty())
+        throw std::invalid_argument("Invalid gameplay configure definition");
+    return {key, argument.substr(equal + 1)};
+}
+void validate_configure_arguments(const BuildConfig& config) {
+    static const std::set<std::string> controlled = {
+        "FASET_GAMEPLAY_SOURCE_DIR", "FASET_ENABLE_LUA", "CMAKE_BUILD_TYPE", "BUILD_TESTING",
+        "FASET_BUILD_EDITOR", "FASET_BUILD_RENDERER", "FASET_BUILD_RUNTIME", "FASET_BUILD_ASSETS"};
+    for (const auto& argument : config.configure_arguments)
+        if (controlled.contains(parse_define(argument).first))
+            throw std::invalid_argument("Cannot override an engine-controlled CMake definition");
+}
+std::string configured_tool(const BuildConfig& config, std::string_view key,
+                            std::string fallback) {
+    if (auto value = configured_cmake_value(config, key))
+        return *value;
+    return fallback;
+}
+fs::path resolve_tool(const std::string& name, const fs::path& working_directory) {
+    const auto supplied = path_from_utf8(name);
+    if (supplied.has_parent_path())
+        return (supplied.is_absolute() ? supplied : working_directory / supplied).lexically_normal();
+    try {
+        return find_executable(name);
+    } catch (const std::exception&) {
+        // CMake reports a missing compiler. Keep the identity deterministic so
+        // fixture build tools can exercise publication without native compiling.
+        return supplied;
+    }
+}
+Json tool_identity(const std::string& name, const fs::path& working_directory) {
+    const auto resolved = resolve_tool(name, working_directory);
+    Json result = {{"path", path_to_utf8(resolved)}};
+    if (fs::is_regular_file(resolved))
+        result["sha256"] = sha256_file(resolved);
+    else
+        result["missing"] = true;
+    return result;
+}
+std::string slang_name(const BuildConfig& config) {
+    auto configured = configured_tool(config, "SLANGC_EXECUTABLE", "");
+    if (!configured.empty())
+        return configured;
+#ifdef _WIN32
+    const auto local = config.engine_root / ".cache/slang/bin/slangc.exe";
+#else
+    const auto local = config.engine_root / ".cache/slang/bin/slangc";
+#endif
+    if (fs::is_regular_file(local))
+        return path_to_utf8(local);
+    if (const char* sdk = std::getenv("VULKAN_SDK")) {
+#ifdef _WIN32
+        const auto sdk_tool = path_from_utf8(sdk) / "Bin/slangc.exe";
+#else
+        const auto sdk_tool = path_from_utf8(sdk) / "bin/slangc";
+#endif
+        if (fs::is_regular_file(sdk_tool))
+            return path_to_utf8(sdk_tool);
+    }
+    return "slangc";
+}
+Json recipe_files(const fs::path& engine_root) {
+    Json files = Json::object();
+    for (const auto& relative : {"CMakeLists.txt", "dependencies.lock.json",
+                                 "tools/compile_shader.py"}) {
+        const auto path = engine_root / relative;
+        files[relative] = fs::is_regular_file(path) ? Json(sha256_file(path)) : Json(nullptr);
+    }
+    const auto cmake = engine_root / "cmake";
+    if (fs::is_directory(cmake))
+        for (const auto& entry : fs::directory_iterator(cmake))
+            if (entry.is_regular_file() && entry.path().extension() == ".cmake")
+                files[generic_path_to_utf8(entry.path().lexically_relative(engine_root))] =
+                    sha256_file(entry.path());
+    return files;
+}
+bool within(const fs::path& path, const fs::path& directory) {
+    const auto relative = path.lexically_relative(directory);
+    if (relative.empty() || relative.is_absolute())
+        return false;
+    for (const auto& component : relative)
+        if (component == "..")
+            return false;
+    return true;
+}
+void refuse_symlink_ancestors(const fs::path& path) {
+    fs::path prefix;
+    for (const auto& component : path) {
+        prefix /= component;
+        std::error_code error;
+        if (fs::is_symlink(fs::symlink_status(prefix, error)))
+            throw std::runtime_error("Native build path contains a symlink: " +
+                                     path_to_utf8(prefix));
+    }
+}
+} // namespace
+
+std::optional<std::string> configured_cmake_value(const BuildConfig& config,
+                                                   std::string_view key) {
+    std::optional<std::string> result;
+    for (const auto& argument : config.configure_arguments) {
+        const auto [name, value] = parse_define(argument);
+        if (name == key)
+            result = value;
+    }
+    return result;
+}
+
+std::string BuildInputs::fingerprint() const {
+    return normalized_hash({{"format", "faset.build-inputs.v1"},
+                            {"source", source_hash},
+                            {"recipe", recipe_hash},
+                            {"toolchain", toolchain_hash}});
+}
+
+std::string gameplay_source_hash(const fs::path& project_root, const scripting::LuaProject& lua) {
+    Json files = Json::object();
+    const auto scripts = project_root / "Scripts";
+    if (fs::is_symlink(fs::symlink_status(scripts)))
+        throw std::runtime_error("Scripts directory must not be a symlink");
+    if (fs::is_directory(scripts))
+        for (const auto& entry : fs::recursive_directory_iterator(scripts)) {
+            if (entry.is_symlink())
+                throw std::runtime_error("Scripts source cannot be a symlink: " +
+                                         path_to_utf8(entry.path()));
+            if (entry.is_regular_file())
+                files[generic_path_to_utf8(entry.path().lexically_relative(project_root))] =
+                    sha256_file(entry.path());
+        }
+    return normalized_hash({{"format", "faset.gameplay-sources.v1"},
+                            {"files", files},
+                            {"lua", lua.fingerprint}});
+}
+
+BuildInputs capture_build_inputs(const BuildConfig& config, const scripting::LuaProject& lua) {
+    validate_configure_arguments(config);
+    BuildInputs result;
+    result.source_hash = gameplay_source_hash(config.project_root, lua);
+    result.recipe_hash = normalized_hash({{"format", "faset.build-recipe.v1"},
+                                          {"generator", config.generator},
+                                          {"configuration", config.configuration},
+                                          {"export_configuration", config.export_configuration},
+                                          {"configure_arguments", config.configure_arguments},
+                                          {"engine_files", recipe_files(config.engine_root)}});
+#ifdef _WIN32
+    constexpr auto default_c = "clang-cl", default_cxx = "clang-cl";
+#else
+    constexpr auto default_c = "clang", default_cxx = "clang++";
+#endif
+    result.toolchain_hash = normalized_hash(
+        {{"format", "faset.native-toolchain.v1"},
+         {"cmake", tool_identity(config.cmake, config.project_root)},
+         {"c", tool_identity(configured_tool(config, "CMAKE_C_COMPILER", default_c),
+                             config.project_root)},
+         {"cxx", tool_identity(configured_tool(config, "CMAKE_CXX_COMPILER", default_cxx),
+                               config.project_root)},
+         {"slang", tool_identity(slang_name(config), config.project_root)},
+         {"toolchain_file", tool_identity(configured_tool(config, "CMAKE_TOOLCHAIN_FILE", ""),
+                                          config.project_root)}});
+    return result;
+}
+
+fs::path stage_gameplay_sources(const BuildConfig& config, const BuildInputs& inputs,
+                                const scripting::LuaProject& lua, std::string_view job_id) {
+    const auto cache = config.cache_root.empty() ? config.project_root / ".faset" / "cache"
+                                                  : config.cache_root;
+    const auto snapshots = cache / "source-snapshots";
+    const auto destination = snapshots / inputs.source_hash;
+    const auto verified = [&](const fs::path& root) {
+        return fs::is_directory(root / "Scripts") && !fs::is_symlink(root) &&
+               gameplay_source_hash(root, lua) == inputs.source_hash;
+    };
+    if (fs::exists(destination)) {
+        if (!verified(destination))
+            throw std::runtime_error("Cached gameplay source snapshot is corrupt");
+        return destination / "Scripts";
+    }
+    const auto source = config.project_root / "Scripts";
+    if (!fs::is_directory(source) || fs::is_symlink(source))
+        throw std::runtime_error("Gameplay Scripts directory is missing or a symlink");
+    const auto staging = snapshots / (".staging-" + std::string(job_id));
+    if (fs::exists(staging))
+        throw std::runtime_error("Gameplay source staging directory already exists");
+    fs::create_directories(staging / "Scripts");
+    try {
+        for (const auto& entry : fs::recursive_directory_iterator(source)) {
+            if (entry.is_symlink())
+                throw std::runtime_error("Gameplay source snapshot contains a symlink");
+            const auto target = staging / "Scripts" / entry.path().lexically_relative(source);
+            if (entry.is_directory())
+                fs::create_directories(target);
+            else if (entry.is_regular_file()) {
+                fs::create_directories(target.parent_path());
+                fs::copy_file(entry.path(), target);
+            }
+        }
+        if (!verified(staging))
+            throw std::runtime_error("Gameplay sources changed while creating the build snapshot");
+        fs::rename(staging, destination);
+        return destination / "Scripts";
+    } catch (...) {
+        std::error_code ignored;
+        fs::remove_all(staging, ignored);
+        if (fs::exists(destination) && verified(destination))
+            return destination / "Scripts";
+        throw;
+    }
+}
+
+void ensure_native_toolchain_stamp(const BuildConfig& config, const fs::path& native_directory,
+                                   const BuildInputs& inputs) {
+    const auto project = fs::absolute(config.project_root).lexically_normal();
+    const auto base = fs::absolute(config.build_directory).lexically_normal();
+    const auto native = fs::absolute(native_directory).lexically_normal();
+    const auto cache = fs::absolute(config.cache_root.empty()
+                                        ? project / ".faset" / "cache"
+                                        : config.cache_root).lexically_normal();
+    const auto engine = fs::absolute(config.engine_root).lexically_normal();
+    if (native.parent_path() != base ||
+        (native.filename() != "Debug" && native.filename() != "Release" &&
+         native.filename() != "RelWithDebInfo"))
+        throw std::runtime_error("Native build path is outside its configured managed root");
+    const auto default_base = project / ".faset" / "build";
+    if ((within(base, project) && base != default_base) || within(project, base) ||
+        within(base, cache) || within(cache, base) || within(base, engine) ||
+        within(engine, base))
+        throw std::runtime_error("Native build root overlaps project, cache or engine files");
+    refuse_symlink_ancestors(native);
+    const auto stamp = native_directory / ".faset-toolchain.json";
+    bool matching = false, owned = false;
+    if (fs::is_regular_file(stamp) && !fs::is_symlink(stamp))
+        try {
+            const auto existing = read_json(stamp);
+            const auto format = existing.value("format", std::string()) ==
+                                "faset.toolchain-stamp";
+            const auto version = existing.value("version", 0);
+            owned = format &&
+                    ((version == 2 &&
+                      existing.value("project_root", std::string()) == path_to_utf8(project) &&
+                      existing.value("native_directory", std::string()) == path_to_utf8(native)) ||
+                     (version == 1 && base == default_base));
+            matching = owned &&
+                       existing.value("toolchain_hash", std::string()) == inputs.toolchain_hash;
+        } catch (const std::exception&) {
+            owned = false;
+        }
+    if (fs::exists(native_directory) && !owned)
+        throw std::runtime_error("Refusing to clear an unowned native build directory: " +
+                                 path_to_utf8(native));
+    if (!matching && fs::exists(native_directory))
+        fs::remove_all(native_directory);
+    fs::create_directories(native_directory);
+    atomic_write_json(stamp, {{"format", "faset.toolchain-stamp"},
+                              {"version", 2},
+                              {"project_root", path_to_utf8(project)},
+                              {"native_directory", path_to_utf8(native)},
+                              {"toolchain_hash", inputs.toolchain_hash}});
+}
+
+std::string build_package_key(const BuildInputs& inputs, const fs::path& native_directory,
+                              const std::string& configuration, const fs::path& player,
+                              const fs::path& exporter) {
+    Json files = Json::object();
+    for (const auto& [name, path] :
+         {std::pair{"player", player}, std::pair{"exporter", exporter},
+          std::pair{"cmake_cache", native_directory / "CMakeCache.txt"}}) {
+        if (!fs::is_regular_file(path) || fs::is_symlink(path))
+            throw std::runtime_error("Native build artifact is missing: " + path_to_utf8(path));
+        files[name] = sha256_file(path);
+    }
+    const auto shaders = native_directory / "shaders";
+    if (!fs::is_directory(shaders))
+        throw std::runtime_error("Native shader directory is missing");
+    for (const auto& entry : fs::recursive_directory_iterator(shaders)) {
+        if (entry.is_symlink())
+            throw std::runtime_error("Native shader is a symlink");
+        if (entry.is_regular_file())
+            files[generic_path_to_utf8(entry.path().lexically_relative(native_directory))] =
+                sha256_file(entry.path());
+    }
+    // On Windows, a changed runtime DLL must also invalidate a package hit.
+    for (const auto& root : {player.parent_path(), native_directory,
+                             native_directory / configuration}) {
+        if (!fs::is_directory(root))
+            continue;
+        for (const auto& entry : fs::directory_iterator(root)) {
+            auto extension = path_to_utf8(entry.path().extension());
+            for (auto& character : extension)
+                character = static_cast<char>(std::tolower(static_cast<unsigned char>(character)));
+            if (extension != ".dll")
+                continue;
+            if (!entry.is_regular_file() || entry.is_symlink())
+                throw std::runtime_error("Native runtime DLL is not a regular file");
+            files["dll:" + path_to_utf8(entry.path().filename())] = sha256_file(entry.path());
+        }
+    }
+    return normalized_hash({{"format", "faset.package-key.v1"},
+                            {"inputs", inputs.fingerprint()},
+                            {"configuration", configuration},
+                            {"files", files}});
+}
+
+bool validate_build_generation(const fs::path& directory, const std::string& package_key) {
+    try {
+        if (!fs::is_directory(directory) || fs::is_symlink(directory))
+            return false;
+        const auto manifest_file = directory / "manifest.json";
+        if (!fs::is_regular_file(manifest_file) || fs::is_symlink(manifest_file))
+            return false;
+        const auto manifest = read_json(manifest_file);
+        if (manifest.at("format") != "faset.build" || manifest.at("version") != 2 ||
+            manifest.at("package_key") != package_key || !manifest.at("files").is_array())
+            return false;
+        std::set<std::string> expected;
+        for (const auto& record : manifest.at("files")) {
+            const auto name = record.at("path").get<std::string>();
+            const auto relative = path_from_utf8(name);
+            if (relative.empty() || relative.is_absolute() || name == "manifest.json" ||
+                generic_path_to_utf8(relative) != name)
+                return false;
+            for (const auto& component : relative)
+                if (component == "." || component == "..")
+                    return false;
+            if (!expected.insert(name).second)
+                return false;
+            auto file = directory;
+            for (const auto& component : relative) {
+                file /= component;
+                if (fs::is_symlink(file))
+                    return false;
+            }
+            if (!fs::is_regular_file(file) || fs::is_symlink(file) ||
+                sha256_file(file) != record.at("sha256").get<std::string>() ||
+                fs::file_size(file) != record.at("size").get<std::uintmax_t>())
+                return false;
+        }
+        for (const auto& entry : fs::recursive_directory_iterator(directory)) {
+            if (entry.is_symlink())
+                return false;
+            if (entry.is_regular_file()) {
+                const auto name = generic_path_to_utf8(entry.path().lexically_relative(directory));
+                if (name != "manifest.json" && !expected.contains(name))
+                    return false;
+            }
+        }
+        const auto player_name = manifest.at("player").get<std::string>();
+        const auto schema_name = manifest.at("schema").get<std::string>();
+        if (!expected.contains(player_name) || !expected.contains(schema_name) ||
+            !expected.contains("faset_schema_exporter" + fs::path(player_name).extension().string()))
+            return false;
+        for (const auto* shader : {"vertexMain", "fragmentMain", "shadowMain",
+                                   "gpuVertexMain", "gpuShadowMain", "gpuCullMain",
+                                   "gpuHzbMain", "gpuPostCullMain"})
+            for (const auto* extension : {".spv", ".reflection.json"})
+                if (!expected.contains("shaders/" + std::string(shader) + extension))
+                    return false;
+        const auto schema = read_json(directory / schema_name);
+        if (schema.at("format") != "faset.schema" || schema.at("version") != 1 ||
+            schema.at("build_fingerprint") != manifest.at("fingerprint"))
+            return false;
+        (void)authoring::gameplay_schemas(schema);
+        return true;
+    } catch (const std::exception&) {
+        return false;
+    }
+}
+
+} // namespace faset::editor

src/editor/build_diagnostics.cpp

@@ -0,0 +1,149 @@
+#include <faset/editor/build_diagnostics.hpp>
+
+#include <faset/core/io.hpp>
+#include <algorithm>
+#include <cctype>
+#include <regex>
+#include <sstream>
+
+namespace faset::editor {
+namespace {
+constexpr std::size_t max_rows = 200;
+constexpr std::size_t max_line = 8192;
+constexpr std::size_t max_message = 2048;
+
+std::string strip_ansi(std::string_view text) {
+    std::string clean;
+    clean.reserve(text.size());
+    for (std::size_t index = 0; index < text.size(); ++index) {
+        if (text[index] == '\x1b' && index + 1 < text.size() && text[index + 1] == '[') {
+            index += 2;
+            while (index < text.size() && !(text[index] >= '@' && text[index] <= '~'))
+                ++index;
+            continue;
+        }
+        clean += text[index];
+    }
+    return clean;
+}
+std::string normalize_path(std::string path) {
+    std::replace(path.begin(), path.end(), '\\', '/');
+    // Compiler output is UTF-8. Constructing a path from a narrow string on
+    // Windows can decode it through the process code page and lose Unicode.
+    path = generic_path_to_utf8(path_from_utf8(path).lexically_normal());
+    while (path.size() > 1 && path.back() == '/')
+        path.pop_back();
+    return path;
+}
+bool has_windows_drive(std::string_view path) {
+    return path.size() >= 2 && std::isalpha(static_cast<unsigned char>(path[0])) &&
+           path[1] == ':';
+}
+std::string lower_ascii(std::string value) {
+    for (auto& character : value)
+        character = static_cast<char>(std::tolower(static_cast<unsigned char>(character)));
+    return value;
+}
+std::string project_source(std::string raw, const std::filesystem::path& project_root) {
+    if (raw.starts_with("lua: "))
+        raw.erase(0, 5);
+    std::replace(raw.begin(), raw.end(), '\\', '/');
+    for (const auto& component : path_from_utf8(raw))
+        if (component == "..")
+            return {};
+    const auto path = normalize_path(std::move(raw));
+    const auto root = normalize_path(path_to_utf8(project_root));
+    std::string relative;
+    if (!path.empty() && path[0] != '/' && !has_windows_drive(path))
+        relative = path;
+    else {
+        const auto windows = has_windows_drive(path) && has_windows_drive(root);
+        const auto comparable_path = windows ? lower_ascii(path) : path;
+        const auto comparable_root = windows ? lower_ascii(root) : root;
+        if (comparable_path.size() <= comparable_root.size() ||
+            !comparable_path.starts_with(comparable_root) ||
+            comparable_path[comparable_root.size()] != '/')
+            return {};
+        relative = path.substr(root.size() + 1);
+    }
+    if (!relative.starts_with("Scripts/") || relative.size() <= 8)
+        return {};
+    if (relative.find("/../") != std::string::npos || relative.ends_with("/.."))
+        return {};
+    return relative;
+}
+int positive_number(const std::string& text) {
+    try {
+        const auto value = std::stoll(text);
+        return value > 0 && value <= 100000000 ? static_cast<int>(value) : 0;
+    } catch (const std::exception&) {
+        return 0;
+    }
+}
+} // namespace
+
+Json parse_build_diagnostics(std::string_view raw_log, std::string_view phase,
+                             const std::filesystem::path& project_root) {
+    static const std::regex msvc(
+        R"(^(.+)\(([0-9]+)(?:,([0-9]+))?\)\s*:\s*(fatal error|error|warning|note)\s*([A-Za-z]+[0-9]+)?\s*:\s*(.*)$)");
+    static const std::regex clang_column(
+        R"(^(.+):([0-9]+):([0-9]+):\s*(fatal error|error|warning|note)(?:\s+([A-Za-z]+[0-9]+))?\s*:\s*(.*)$)");
+    static const std::regex clang_line(
+        R"(^(.+):([0-9]+):\s*(fatal error|error|warning|note)(?:\s+([A-Za-z]+[0-9]+))?\s*:\s*(.*)$)");
+    static const std::regex lua(R"(^(.+\.lua):([0-9]+):\s*(.*)$)");
+    Json rows = Json::array();
+    std::istringstream stream{std::string(raw_log)};
+    std::string raw;
+    while (rows.size() < max_rows && std::getline(stream, raw)) {
+        if (raw.size() > max_line)
+            raw.resize(max_line);
+        auto line = strip_ansi(raw);
+        if (!line.empty() && line.back() == '\r')
+            line.pop_back();
+        std::smatch match;
+        std::string file, message, severity, code;
+        int row = 0, column = 0;
+        bool has_column = false;
+        if (std::regex_match(line, match, msvc) ||
+            std::regex_match(line, match, clang_column)) {
+            file = match[1].str();
+            row = positive_number(match[2].str());
+            has_column = !match[3].str().empty();
+            column = positive_number(match[3].str());
+            severity = match[4].str();
+            code = match[5].str();
+            message = match[6].str();
+        } else if (std::regex_match(line, match, clang_line)) {
+            file = match[1].str();
+            row = positive_number(match[2].str());
+            severity = match[3].str();
+            code = match[4].str();
+            message = match[5].str();
+        } else if (std::regex_match(line, match, lua)) {
+            file = match[1].str();
+            row = positive_number(match[2].str());
+            severity = "error";
+            message = match[3].str();
+        } else
+            continue;
+        if (row == 0 || (has_column && column == 0))
+            continue;
+        if (severity == "fatal error")
+            severity = "error";
+        if (message.size() > max_message)
+            message.resize(max_message);
+        Json diagnostic{{"severity", severity},
+                        {"phase", std::string(phase)},
+                        {"message", message},
+                        {"line", row}};
+        if (column > 0)
+            diagnostic["column"] = column;
+        if (!code.empty())
+            diagnostic["code"] = code;
+        if (auto relative = project_source(file, project_root); !relative.empty())
+            diagnostic["file"] = std::move(relative);
+        rows.push_back(std::move(diagnostic));
+    }
+    return rows;
+}
+} // namespace faset::editor

src/editor/build_service.cpp

@@ -1,3 +1,4 @@
+#include <algorithm>
 #include <atomic>
 #include <cctype>
 #include <chrono>
@@ -6,9 +7,12 @@
 #include <faset/assets/asset_data.hpp>
 #include <faset/assets/asset_pipeline.hpp>
 #include <faset/authoring/schema.hpp>
+#include <faset/authoring/service.hpp>
 #include <faset/core/hash.hpp>
 #include <faset/core/io.hpp>
 #include <faset/core/process.hpp>
+#include <faset/editor/build_cache.hpp>
+#include <faset/editor/build_diagnostics.hpp>
 #include <faset/editor/build_service.hpp>
 #include <faset/scripting/project.hpp>
 #include <fstream>
@@ -89,11 +93,107 @@ fs::path build_executable(const fs::path& build, const std::string& configuratio
     }
     throw std::runtime_error("Build did not produce " + target);
 }
+Json starter_scene(const std::string& name, int dimension, std::string_view language) {
+    const auto schemas = authoring::builtin_schemas();
+    auto scene = authoring::make_scene(name + " — Starter", dimension);
+    scene["simulation"] = authoring::default_simulation_settings();
+    auto add_component = [&](Json& entity, std::string type, Json fields) {
+        entity["components"].push_back({{"id", new_id()},
+                                        {"type", std::move(type)},
+                                        {"version", 1},
+                                        {"fields", std::move(fields)}});
+    };
+    auto ground = authoring::make_entity(schemas, "Ground");
+    auto& ground_pose = ground["components"][0]["fields"];
+    ground_pose["position"] = {0, -1, 0};
+    ground_pose["scale"] = dimension == 2 ? Json::array({12, 1, 1}) : Json::array({12, 1, 12});
+    if (dimension == 2) {
+        add_component(ground, "faset.sprite", {{"size", {1, 1}},
+                                                {"color", {0.20, 0.25, 0.31, 1}}});
+    } else {
+        add_component(ground, "faset.mesh", {{"asset", "builtin:cube"},
+                                              {"color", {0.20, 0.25, 0.31, 1}}});
+    }
+    auto ground_body = schemas.default_fields("faset.rigid_body_" + std::to_string(dimension) +
+                                              "d");
+    ground_body["body_type"] = "static";
+    add_component(ground, "faset.rigid_body_" + std::to_string(dimension) + "d",
+                  std::move(ground_body));
+    scene["entities"].push_back(std::move(ground));
+
+    auto actor = authoring::make_entity(schemas, "Player");
+    actor["components"][0]["fields"]["position"] = {0, 1, 0};
+    if (dimension == 2) {
+        add_component(actor, "faset.sprite", {{"size", {0.8, 0.8}},
+                                               {"color", {0.25, 0.72, 0.85, 1}}});
+    } else {
+        actor["components"][0]["fields"]["scale"] = {0.8, 0.8, 0.8};
+        add_component(actor, "faset.mesh", {{"asset", "builtin:cube"},
+                                             {"color", {0.25, 0.72, 0.85, 1}}});
+    }
+    add_component(actor, "faset.rigid_body_" + std::to_string(dimension) + "d",
+                  schemas.default_fields("faset.rigid_body_" + std::to_string(dimension) + "d"));
+    add_component(actor, language == "lua" ? "starter.player" : "gameplay.character",
+                  {{"speed", 4.0}, {"jump_speed", 5.0}});
+    scene["entities"].push_back(std::move(actor));
+    if (dimension == 3) {
+        auto camera = authoring::make_entity(schemas, "Camera");
+        camera["components"][0]["fields"]["position"] = {0, 2.5, 8};
+        camera["components"][0]["fields"]["rotation"] = {-0.18, 0, 0};
+        add_component(camera, "faset.camera", schemas.default_fields("faset.camera"));
+        scene["entities"].push_back(std::move(camera));
+        auto sun = authoring::make_entity(schemas, "Sun");
+        add_component(sun, "faset.light", schemas.default_fields("faset.light"));
+        scene["entities"].push_back(std::move(sun));
+    }
+    // Validate every built-in component now; the behavior component is validated by
+    // SchemaExporter from the selected C++/Lua module during the first build.
+    auto builtins = scene;
+    for (auto& entity : builtins["entities"]) {
+        auto& components = entity["components"].get_ref<Json::array_t&>();
+        std::erase_if(components, [](const Json& component) {
+            return !component.at("type").get<std::string>().starts_with("faset.");
+        });
+    }
+    authoring::validate_scene(builtins, schemas);
+    return scene;
+}
+struct StarterCreateLock {
+    fs::path path;
+    explicit StarterCreateLock(const fs::path& root) : path(root / ".faset/starter-create.lock") {
+        if (!fs::create_directory(path))
+            throw std::runtime_error("Another project creation is in progress; remove a stale " +
+                                     path_to_utf8(path) + " only after closing that Editor");
+    }
+    ~StarterCreateLock() {
+        std::error_code ignored;
+        fs::remove_all(path, ignored);
+    }
+    StarterCreateLock(const StarterCreateLock&) = delete;
+    StarterCreateLock& operator=(const StarterCreateLock&) = delete;
+};
+void require_new_starter_directory(const fs::path& root) {
+    // BuildService creates .faset/cache in its constructor. Any other content is
+    // user-owned, including a previous starter, and must be left intact.
+    for (const auto& entry : fs::directory_iterator(root)) {
+        if (entry.path().filename() != ".faset" || !entry.is_directory() ||
+            entry.is_symlink())
+            throw std::runtime_error("Create requires a new or empty project directory");
+        for (const auto& internal : fs::directory_iterator(entry.path())) {
+            if (internal.path().filename() == "starter-create.lock" &&
+                internal.is_directory() && !internal.is_symlink())
+                continue;
+            if (internal.path().filename() != "cache" || !internal.is_directory() ||
+                internal.is_symlink() || !fs::is_empty(internal.path()))
+                throw std::runtime_error("Create requires a new or empty project directory");
+        }
+    }
+}
 } // namespace
 Json JobStatus::json() const {
     return {{"id", id},       {"kind", kind},         {"state", state},
             {"stage", stage}, {"progress", progress}, {"log", log},
-            {"error", error}, {"result", result}};
+            {"error", error}, {"diagnostics", diagnostics}, {"result", result}};
 }
 void write_cooked_scene(const fs::path& path, const Json& scene) {
     validate_scene(scene);
@@ -198,6 +298,13 @@ struct BuildService::Impl {
     std::string run(Job& job, std::vector<std::string> arguments, const fs::path& cwd) {
         if (job.cancelled)
             throw Cancelled{};
+        std::string phase;
+        std::size_t diagnostics_before;
+        {
+            std::lock_guard lock(job.mutex);
+            phase = job.status.stage;
+            diagnostics_before = job.status.diagnostics.size();
+        }
         std::string description = "$";
         for (const auto& argument : arguments)
             description += " " + Json(argument).dump();
@@ -205,6 +312,35 @@ struct BuildService::Impl {
         log(job, description);
         Process process({std::move(arguments), cwd, {}});
         std::string output;
+        std::string pending;
+        const auto collect_diagnostics = [&](std::string_view chunk, bool final) {
+            pending.append(chunk);
+            std::size_t newline;
+            while ((newline = pending.find('\n')) != std::string::npos) {
+                const auto line = pending.substr(0, newline + 1);
+                pending.erase(0, newline + 1);
+                const auto found = parse_build_diagnostics(line, phase, config.project_root);
+                if (found.empty())
+                    continue;
+                std::lock_guard lock(job.mutex);
+                for (const auto& row : found) {
+                    if (job.status.diagnostics.size() >= 200)
+                        break;
+                    job.status.diagnostics.push_back(row);
+                }
+            }
+            if (final && !pending.empty()) {
+                const auto found = parse_build_diagnostics(pending, phase, config.project_root);
+                std::lock_guard lock(job.mutex);
+                for (const auto& row : found) {
+                    if (job.status.diagnostics.size() >= 200)
+                        break;
+                    job.status.diagnostics.push_back(row);
+                }
+                pending.clear();
+            } else if (pending.size() > 8192)
+                pending.erase(0, pending.size() - 8192);
+        };
         while (true) {
             if (job.cancelled) {
                 process.cancel();
@@ -214,14 +350,29 @@ struct BuildService::Impl {
             }
             auto poll = process.poll();
             log(job, poll.output);
+            collect_diagnostics(poll.output, !poll.running);
             output += poll.output;
             if (output.size() > max_log_bytes)
                 output.erase(0, output.size() - max_log_bytes);
             if (!poll.running) {
-                if (poll.exit_code.value_or(1) != 0)
+                if (poll.exit_code.value_or(1) != 0) {
+                    std::lock_guard lock(job.mutex);
+                    bool has_error = false;
+                    for (std::size_t index = diagnostics_before;
+                         index < job.status.diagnostics.size(); ++index)
+                        if (job.status.diagnostics[index].value("severity", "") == "error")
+                            has_error = true;
+                    if (!has_error && job.status.diagnostics.size() < 200)
+                        job.status.diagnostics.push_back(
+                            {{"severity", "error"},
+                             {"phase", phase},
+                             {"message", "Process exited with code " +
+                                             std::to_string(poll.exit_code.value_or(1)) +
+                                             "; see job log"}});
                     throw std::runtime_error("Process exited with code " +
                                              std::to_string(poll.exit_code.value_or(1)) +
                                              "; see job log");
+                }
                 return output;
             }
             std::this_thread::sleep_for(std::chrono::milliseconds(15));
@@ -240,19 +391,23 @@ struct BuildService::Impl {
         }
     }
     Json build(Job& job, bool exporting = false) {
+        const auto started = std::chrono::steady_clock::now();
+        const auto milliseconds = [](auto from, auto to) {
+            return std::chrono::duration_cast<std::chrono::milliseconds>(to - from).count();
+        };
         const auto& configuration = exporting ? config.export_configuration : config.configuration;
         const auto native_directory = config.build_directory / configuration;
         checkpoint(job, "Configuring gameplay", .05);
         job.lua = scripting::loadLuaProject(config.project_root);
-        const auto cpp = config.project_root / "Scripts" / "Gameplay.cpp";
-        const auto hpp = config.project_root / "Scripts" / "Gameplay.hpp";
+        const auto inputs = capture_build_inputs(config, job.lua);
+        const auto staged_scripts = stage_gameplay_sources(config, inputs, job.lua, job.status.id);
+        const auto cpp = staged_scripts / "Gameplay.cpp";
+        const auto hpp = staged_scripts / "Gameplay.hpp";
         const bool has_cpp = fs::is_regular_file(cpp), has_hpp = fs::is_regular_file(hpp);
         if (has_cpp != has_hpp || (!has_cpp && !job.lua.enabled()))
             throw std::runtime_error("Project requires Scripts/Gameplay.cpp and Gameplay.hpp, "
                                      "or Lua entry scripts declared in project.faset.json");
-        const auto cpp_source = has_cpp ? read_text(cpp) : std::string{};
-        const auto hpp_source = has_hpp ? read_text(hpp) : std::string{};
-        fs::create_directories(native_directory);
+        ensure_native_toolchain_stamp(config, native_directory, inputs);
         std::vector<std::string> arguments = {config.cmake,
                                               "-S",
                                               path_to_utf8(config.engine_root),
@@ -267,37 +422,100 @@ struct BuildService::Impl {
                                               "-DFASET_BUILD_RUNTIME=ON",
                                               "-DFASET_BUILD_ASSETS=ON",
                                               "-DFASET_GAMEPLAY_SOURCE_DIR=" +
-                                                  path_to_utf8(config.project_root / "Scripts")};
-        bool compiler_overridden = false;
-        for (const auto& arg : config.configure_arguments)
-            if (arg.starts_with("-DCMAKE_CXX_COMPILER="))
-                compiler_overridden = true;
-        if (!compiler_overridden) {
+                                                  path_to_utf8(staged_scripts)};
+        if (!configured_cmake_value(config, "CMAKE_C_COMPILER")) {
 #ifdef _WIN32
             auto compiler = find_executable("clang-cl");
             arguments.push_back("-DCMAKE_C_COMPILER=" + path_to_utf8(compiler));
-            arguments.push_back("-DCMAKE_CXX_COMPILER=" + path_to_utf8(compiler));
 #else
             arguments.push_back("-DCMAKE_C_COMPILER=" + path_to_utf8(find_executable("clang")));
+#endif
+        }
+        if (!configured_cmake_value(config, "CMAKE_CXX_COMPILER")) {
+#ifdef _WIN32
+            arguments.push_back("-DCMAKE_CXX_COMPILER=" +
+                                path_to_utf8(find_executable("clang-cl")));
+#else
             arguments.push_back("-DCMAKE_CXX_COMPILER=" + path_to_utf8(find_executable("clang++")));
 #endif
         }
-        arguments.insert(arguments.end(), config.configure_arguments.begin(),
-                         config.configure_arguments.end());
+        for (const auto& argument : config.configure_arguments) {
+            const auto equal = argument.find('=');
+            const auto colon = argument.find(':', 2);
+            const auto key = argument.substr(2, colon < equal ? colon - 2 : equal - 2);
+            if (key == "CMAKE_C_COMPILER" || key == "CMAKE_CXX_COMPILER" ||
+                key == "SLANGC_EXECUTABLE" || key == "CMAKE_TOOLCHAIN_FILE") {
+                const auto value = path_from_utf8(argument.substr(equal + 1));
+                if (value.has_parent_path() && value.is_relative()) {
+                    arguments.push_back(argument.substr(0, equal + 1) +
+                                        path_to_utf8((config.project_root / value).lexically_normal()));
+                    continue;
+                }
+            }
+            arguments.push_back(argument);
+        }
         arguments.push_back("-DCMAKE_BUILD_TYPE=" + configuration);
         // Project declarations, not a stale cache or a user-supplied override, determine
         // whether the packaged game has a Lua VM linked into it.
         arguments.push_back(std::string("-DFASET_ENABLE_LUA=") +
                             (job.lua.enabled() ? "ON" : "OFF"));
         run(job, std::move(arguments), config.project_root);
+        const auto configured = std::chrono::steady_clock::now();
         checkpoint(job, "Compiling and linking Player", .25);
         run(job,
             {config.cmake, "--build", path_to_utf8(native_directory), "--config", configuration,
              "--parallel", "4", "--target", "faset_player", "faset_schema_exporter"},
             config.project_root);
-        checkpoint(job, "Exporting gameplay schema", .58);
+        const auto compiled = std::chrono::steady_clock::now();
         auto player = build_executable(native_directory, configuration, "faset_player");
         auto exporter = build_executable(native_directory, configuration, "faset_schema_exporter");
+        const auto package_key =
+            build_package_key(inputs, native_directory, configuration, player, exporter);
+        const auto source_unchanged = [&] {
+            if (gameplay_source_hash(config.project_root,
+                                     scripting::loadLuaProject(config.project_root)) !=
+                inputs.source_hash)
+                throw std::runtime_error("Gameplay sources changed during the build; build again");
+        };
+        const auto result_for = [&](const std::string& id, const std::string& fingerprint,
+                                    bool reused) -> Json {
+            const auto directory = config.cache_root / "builds" / id;
+            const auto finished = std::chrono::steady_clock::now();
+            return {{"generation", id},
+                    {"directory", path_to_utf8(directory)},
+                    {"build_directory", path_to_utf8(native_directory)},
+                    {"configuration", configuration},
+                    {"player", path_to_utf8(directory / ("faset_player" + executable_suffix()))},
+                    {"schema", path_to_utf8(directory / "schema.json")},
+                    {"lua_enabled", job.lua.enabled()},
+                    {"lua_fingerprint", job.lua.fingerprint},
+                    {"fingerprint", fingerprint},
+                    {"schema_cache_hit", reused},
+                    {"generation_reused", reused},
+                    {"phase_times_ms",
+                     {{"configure", milliseconds(started, configured)},
+                      {"native_build", milliseconds(configured, compiled)},
+                      {"schema_package", reused ? 0 : milliseconds(compiled, finished)},
+                      {"total", milliseconds(started, finished)}}}};
+        };
+        const auto pointer_file = config.cache_root / "last_build.json";
+        if (fs::is_regular_file(pointer_file))
+            try {
+                const auto pointer = read_json(pointer_file);
+                const auto id = pointer.at("generation").get<std::string>();
+                const auto candidate =
+                    project_path(config.cache_root, fs::path("builds") / id);
+                if (validate_build_generation(candidate, package_key)) {
+                    source_unchanged();
+                    checkpoint(job, "Reusing verified build generation", .68);
+                    const auto manifest = read_json(candidate / "manifest.json");
+                    log(job, "Verified schema/package cache hit: " + id + "\n");
+                    return result_for(id, manifest.at("fingerprint").get<std::string>(), true);
+                }
+            } catch (const std::exception&) {
+                // A bad pointer or old/corrupt generation is a cache miss.
+            }
+        checkpoint(job, "Exporting gameplay schema", .58);
         const auto staging = config.cache_root / "builds" / (".staging-" + job.status.id);
         const auto generation = config.cache_root / "builds" / job.status.id;
         fs::create_directories(staging);
@@ -322,10 +540,7 @@ struct BuildService::Impl {
             // Validate the complete metadata before publishing either the schema or
             // its Player generation. Session uses this same authoring contract.
             (void)authoring::gameplay_schemas(schema);
-            std::string fingerprint = sha256_file(player) + sha256_file(exporter) +
-                                      read_text(native_directory / "CMakeCache.txt");
-            fingerprint += cpp_source + hpp_source + job.lua.fingerprint;
-            fingerprint = sha256(fingerprint);
+            const auto fingerprint = package_key;
             schema["build_fingerprint"] = fingerprint;
             if (job.lua.enabled())
                 schema["lua_fingerprint"] = job.lua.fingerprint;
@@ -333,7 +548,6 @@ struct BuildService::Impl {
             copy_required_file(player, staging / ("faset_player" + executable_suffix()));
             copy_required_file(exporter, staging / ("faset_schema_exporter" + executable_suffix()));
             for (const auto* file : {"vertexMain.spv", "fragmentMain.spv", "shadowMain.spv",
-                                     "lightTileMain.spv", "lightTileMain.reflection.json",
                                      "vertexMain.reflection.json", "fragmentMain.reflection.json",
                                      "shadowMain.reflection.json", "gpuVertexMain.spv",
                                      "gpuShadowMain.spv", "gpuCullMain.spv", "gpuHzbMain.spv",
@@ -342,36 +556,39 @@ struct BuildService::Impl {
                                      "gpuHzbMain.reflection.json", "gpuPostCullMain.reflection.json"})
                 copy_required_file(native_directory / "shaders" / file, staging / "shaders" / file);
             copy_runtime_libraries(job, player, staging, native_directory, configuration);
+            Json files = Json::array();
+            for (const auto& entry : fs::recursive_directory_iterator(staging)) {
+                if (entry.is_symlink())
+                    throw std::runtime_error("Build generation contains a symlink");
+                if (entry.is_regular_file())
+                    files.push_back(
+                        {{"path", generic_path_to_utf8(entry.path().lexically_relative(staging))},
+                         {"sha256", sha256_file(entry.path())},
+                         {"size", entry.file_size()}});
+            }
             Json manifest{{"format", "faset.build"},
-                          {"version", 1},
+                          {"version", 2},
                           {"id", job.status.id},
                           {"fingerprint", fingerprint},
+                          {"package_key", package_key},
                           {"configuration", configuration},
                           {"lua_enabled", job.lua.enabled()},
                           {"lua_fingerprint", job.lua.fingerprint},
                           {"player", "faset_player" + executable_suffix()},
-                          {"schema", "schema.json"}};
+                          {"schema", "schema.json"},
+                          {"files", files}};
             atomic_write_json(staging / "manifest.json", manifest);
             checkpoint(job, "Publishing build generation", .68);
             if (job.lua.enabled() &&
                 scripting::loadLuaProject(staging).fingerprint != job.lua.fingerprint)
                 throw std::runtime_error("Lua build snapshot changed during schema export");
-            if (scripting::loadLuaProject(config.project_root).fingerprint != job.lua.fingerprint ||
-                has_cpp != fs::is_regular_file(cpp) || has_hpp != fs::is_regular_file(hpp) ||
-                (has_cpp && (read_text(cpp) != cpp_source || read_text(hpp) != hpp_source)))
-                throw std::runtime_error("Gameplay sources changed during the build; build again");
+            source_unchanged();
+            if (!validate_build_generation(staging, package_key))
+                throw std::runtime_error("Build generation failed final integrity validation");
             fs::rename(staging, generation);
             atomic_write_json(config.cache_root / "last_build.json",
                               {{"generation", job.status.id}, {"fingerprint", fingerprint}});
-            return {{"generation", job.status.id},
-                    {"directory", path_to_utf8(generation)},
-                    {"build_directory", path_to_utf8(native_directory)},
-                    {"configuration", configuration},
-                    {"player", path_to_utf8(generation / ("faset_player" + executable_suffix()))},
-                    {"schema", path_to_utf8(generation / "schema.json")},
-                    {"lua_enabled", job.lua.enabled()},
-                    {"lua_fingerprint", job.lua.fingerprint},
-                    {"fingerprint", fingerprint}};
+            return result_for(job.status.id, fingerprint, false);
         } catch (...) {
             std::error_code error;
             fs::remove_all(staging, error);
@@ -586,7 +803,6 @@ struct BuildService::Impl {
             copy_required_file(build_directory / ("faset_player" + executable_suffix()),
                                staging / ("faset_player" + executable_suffix()));
             for (const auto* shader : {"vertexMain.spv", "fragmentMain.spv", "shadowMain.spv",
-                                       "lightTileMain.spv", "lightTileMain.reflection.json",
                                        "vertexMain.reflection.json", "fragmentMain.reflection.json",
                                        "shadowMain.reflection.json", "gpuVertexMain.spv",
                                        "gpuShadowMain.spv", "gpuCullMain.spv", "gpuHzbMain.spv",
@@ -787,6 +1003,97 @@ void BuildService::scaffold(const std::string& name, int dimension) {
     if (!fs::exists(c.project_root / ".gitignore"))
         atomic_write(c.project_root / ".gitignore", ".faset/\nExports/\n");
 }
+void BuildService::scaffold(const std::string& name, int dimension,
+                            std::string_view language) {
+    if (name.empty() || (dimension != 2 && dimension != 3) ||
+        (language != "cpp" && language != "lua"))
+        throw std::invalid_argument("Starter requires a name, 2D/3D and cpp/lua language");
+    const auto& c = impl_->config;
+    StarterCreateLock lock(c.project_root);
+    require_new_starter_directory(c.project_root);
+    const auto scene = starter_scene(name, dimension, language);
+    const auto source = c.engine_root / "tools/project_templates" /
+                        (language == "lua" ? "lua-main.lua" : "Gameplay.cpp");
+    const auto module = read_text(source);
+    const auto header = language == "cpp"
+                            ? read_text(c.engine_root / "tools/project_templates/Gameplay.hpp")
+                            : std::string();
+    const auto lua_annotations = language == "lua"
+                                     ? read_text(c.engine_root / "tools/lua/faset.lua")
+                                     : std::string();
+    const auto lua_config = language == "lua"
+                                ? read_json(c.engine_root / "tools/lua/luarc.json")
+                                : Json();
+    const auto lua_scripts_config =
+        language == "lua" ? read_json(c.engine_root / "tools/lua/luarc-scripts.json") : Json();
+    const auto stage = lock.path / "staged";
+    fs::create_directories(stage / "Scripts");
+    fs::create_directories(stage / "Scenes");
+    fs::create_directories(stage / "Assets");
+    if (language == "cpp") {
+        atomic_write(stage / "Scripts/Gameplay.cpp", module);
+        atomic_write(stage / "Scripts/Gameplay.hpp", header);
+    } else {
+        atomic_write(stage / "Scripts/main.lua", module);
+        atomic_write(stage / ".faset/lua/faset.lua", lua_annotations);
+        atomic_write_json(stage / ".luarc.json", lua_config);
+        atomic_write_json(stage / "Scripts/.luarc.json", lua_scripts_config);
+    }
+    atomic_write_json(stage / "Scenes/main.scene.json", scene);
+    Json project = {{"format", "faset.project"},
+                    {"version", 1},
+                    {"id", new_id()},
+                    {"name", name},
+                    {"dimension", dimension},
+                    {"start_scene", "Scenes/main.scene.json"}};
+    if (language == "lua")
+        project["scripting"] = {{"lua", {{"scripts", Json::array({"Scripts/main.lua"})}}}};
+    atomic_write_json(stage / "project.faset.json", project);
+    atomic_write(stage / ".gitignore",
+                 ".faset/*\n!.faset/lua/\n.faset/lua/*\n!.faset/lua/faset.lua\nExports/\n");
+    std::vector<std::pair<fs::path, std::string>> created;
+    auto publish = [&](const fs::path& relative) {
+        const auto source = stage / relative;
+        const auto target = c.project_root / relative;
+        fs::create_directories(target.parent_path());
+        if (!fs::copy_file(source, target, fs::copy_options::none))
+            throw std::runtime_error("Starter destination appeared during creation: " +
+                                     path_to_utf8(target));
+        created.emplace_back(target, sha256_file(source));
+    };
+    try {
+        publish(".gitignore");
+        if (language == "cpp") {
+            publish("Scripts/Gameplay.cpp");
+            publish("Scripts/Gameplay.hpp");
+        } else {
+            publish("Scripts/main.lua");
+            publish(".faset/lua/faset.lua");
+            publish(".luarc.json");
+            publish("Scripts/.luarc.json");
+        }
+        publish("Scenes/main.scene.json");
+        fs::create_directory(c.project_root / "Assets");
+        // The manifest is the final commit marker: an interrupted create has no
+        // valid project record and never replaces an existing project file.
+        publish("project.faset.json");
+    } catch (...) {
+        for (auto it = created.rbegin(); it != created.rend(); ++it) {
+            try {
+                std::error_code ignored;
+                if (fs::is_regular_file(it->first, ignored) &&
+                    sha256_file(it->first) == it->second)
+                    fs::remove(it->first, ignored);
+            } catch (...) { /* Preserve the original create failure. */
+            }
+        }
+        for (const auto& relative : {"Assets", "Scenes", "Scripts", ".faset/lua"}) {
+            std::error_code ignored;
+            fs::remove(c.project_root / relative, ignored); // Empty directories only.
+        }
+        throw;
+    }
+}
 std::string BuildService::start_build() {
     return impl_->enqueue("build");
 }

src/editor/commands.cpp

@@ -103,9 +103,13 @@ Commands::Commands(authoring::AuthoringService& authoring) : authoring_(authorin
         [&](const Json& args) { return authoring_.query(args.at("document")); }, true);
     add("faset_document_save",
         "Atomically save an authoring document. Refuses to overwrite an externally modified file.",
-        object_schema({{"document", text}, {"path", text}}, {"document"}), [&](const Json& args) {
+        object_schema({{"document", text}, {"path", text},
+                       {"expected_revision", integer}}, {"document"}), [&](const Json& args) {
+            std::optional<std::uint64_t> expected;
+            if (args.contains("expected_revision"))
+                expected = args.at("expected_revision").get<std::uint64_t>();
             return authoring_.save(args.at("document"),
-                                   path_from_utf8(args.value("path", std::string())));
+                                   path_from_utf8(args.value("path", std::string())), expected);
         });
     add(
         "faset_schema",

src/editor/debug_overlay.cpp

@@ -381,35 +381,6 @@ void DebugOverlay::append(render::Snapshot& output, render::Renderer& renderer,
             ImGui::Text("Prepared LOD: %u / %u / %u / %u+", stats.lod_counts[0],
                         stats.lod_counts[1], stats.lod_counts[2], stats.lod_counts[3]);
             ImGui::Separator();
-            ImGui::TextUnformatted("Lighting and shadows");
-            ImGui::Text("Lighting path: %s", stats.effective_lighting_path.c_str());
-            ImGui::Text("Light tiles: %u; GPU build %.2f ms",
-                        stats.light_tile_count, stats.gpu_light_tiles_ms);
-            if (stats.light_tile_counts_valid)
-                ImGui::Text("Tile entries: %u; overflow tiles: %u",
-                            stats.light_tile_candidate_count,
-                            stats.light_tile_overflow_count);
-            else if (stats.light_tile_count)
-                ImGui::TextDisabled("Tile entry counts unavailable until diagnostics readback");
-            ImGui::Text("Local lights: %u submitted, %u omitted",
-                        stats.submitted_local_lights, stats.omitted_local_lights);
-            ImGui::Text("Sun cascades: %u / %u effective",
-                        stats.requested_sun_cascades, stats.effective_sun_cascades);
-            ImGui::Text("Local faces: %u requested, %u rasterized (%u tiles)",
-                        stats.requested_local_shadow_faces, stats.local_shadow_faces,
-                        stats.local_shadow_tiles);
-            ImGui::Text("Dropped faces: %u (point %u, atlas %u, draw budget %u, unavailable %u)",
-                        stats.dropped_shadow_faces, stats.dropped_point_shadow_faces,
-                        stats.shadow_atlas_full_drops, stats.shadow_caster_budget_drops,
-                        stats.shadow_unavailable_drops);
-            ImGui::Text("Shadow caster draws: %u / 4096", stats.shadow_caster_draws);
-            ImGui::Text("Atlas memory: sun %.1f MiB, local %.1f MiB",
-                        double(stats.sun_shadow_atlas_bytes) / 1048576.0,
-                        double(stats.local_shadow_atlas_bytes) / 1048576.0);
-            if (stats.gpu_ms > 0)
-                ImGui::Text("Shadow GPU: sun %.2f ms, local %.2f ms",
-                            stats.gpu_sun_shadow_ms, stats.gpu_local_shadow_ms);
-            ImGui::Separator();
             ImGui::Text("Vulkan allocations: %.2f MiB",
                         double(stats.gpu_allocated_bytes) / 1048576.0);
             ImGui::Text("Validation: %s   Errors: %u",

src/editor/editor_ui.cpp

@@ -168,7 +168,7 @@ struct EditorUI::Impl {
     Json instance_selection = Json::array(), template_conflicts = Json::array();
     std::string document, selected, source_file, asset_filter,
         active_bottom = "assets", menu, command_name = "faset_documents", status = "Ready",
-        gizmo_mode = "Move";
+        gizmo_mode = "Move", expanded_job_log;
     Json current, resolved, files = Json::array(), assets = Json::array(), schemas = Json::object(),
                             recovery = Json::array();
     std::uint64_t shown_revision = std::numeric_limits<std::uint64_t>::max();
@@ -186,6 +186,7 @@ struct EditorUI::Impl {
     bool project_settings_open = false;
     Json project_settings_state;
     int project_settings_dimension = 3;
+    bool project_settings_autosave = true;
     std::string project_settings_error;
     bool project_switch_enabled = true, project_switch_requested = false,
          project_switch_warning = false;
@@ -601,6 +602,20 @@ struct EditorUI::Impl {
         schema_status.visible = false;
         schema_status.enabled = false;
         schema_status.tooltip = "Choose Build to refresh gameplay fields in Inspector";
+        auto& autosave_status = statusrow.add(Kind::Label, "autosave-status", "Saved");
+        autosave_status.layout.width = 160;
+        autosave_status.enabled = false;
+        auto& autosave_action = button(statusrow, "autosave-save-as", "Save As...", [this] {
+            const auto path = current.value("path", std::string());
+            const auto directory = path.empty() ? std::string("Scenes/")
+                                                : path.substr(0, path.find_last_of('/') + 1);
+            ui.update_text("save-path",
+                           directory + "Recovered-" + new_id().substr(0, 8) + ".scene.json",
+                           true);
+            menu = "File";
+        }, 100);
+        autosave_action.visible = false;
+        autosave_action.tooltip = "Save this scene to a new project-relative path";
         label(statusrow, "renderer-status", "Vulkan", 225);
         statusrow.find("renderer-status")->enabled = false;
         build_overlays();
@@ -792,12 +807,20 @@ struct EditorUI::Impl {
         }
         label(project, "project-settings-start-label", "Start scene (saved project-relative path)");
         project.add(Kind::TextField, "project-settings-start");
+        auto& autosave = project.add(Kind::Checkbox, "project-settings-autosave",
+                                     "Autosave named scenes after 2 seconds idle");
+        autosave.layout.height = 30;
+        autosave.checked = true;
+        autosave.on_commit = [this](Widget& widget) {
+            project_settings_autosave = widget.checked;
+        };
+        autosave.tooltip = "Unsaved scenes remain in recovery until you choose Save As";
         auto& scenes = project.add(Kind::Column, "project-settings-scenes");
         scenes.layout.height = 104;
         scenes.layout.scroll = true;
         scenes.layout.gap = 1;
         label(project, "project-settings-note",
-              "Applies on next project open. Scene Undo is unchanged.");
+              "Autosave applies now; other settings on next open. Scene Undo is unchanged.");
         auto& project_actions = project.add(Kind::Row, "project-settings-actions");
         project_actions.layout.height = 32;
         button(
@@ -1258,6 +1281,42 @@ struct EditorUI::Impl {
                                          (current.value("dirty", false) ? " *" : "");
         ui.find("project-title")->tooltip = project_name + " / " + scene_name;
         ui.find("status")->text = status;
+        const auto autosave = call("faset_autosave_status");
+        std::string save_state = "saved", save_error;
+        if (!autosave.is_null()) {
+            if (!autosave.value("enabled", true))
+                save_state = "disabled";
+            for (const auto& entry : autosave.at("documents"))
+                if (entry.at("id") == document) {
+                    save_state = entry.at("state").get<std::string>();
+                    save_error = entry.value("error", std::string());
+                    break;
+                }
+            if (!autosave.value("enabled", true) && save_state == "saved")
+                save_state = "disabled";
+        }
+        auto& save_label = *ui.find("autosave-status");
+        save_label.text = save_state == "pending"          ? "Pending autosave"
+                          : save_state == "saving"         ? "Saving"
+                          : save_state == "conflict"       ? "Save conflict"
+                          : save_state == "failed"         ? "Save failed"
+                          : save_state == "save_as_required" ? "Save As required"
+                          : save_state == "disabled"       ? "Autosave off"
+                                                           : "Saved";
+        save_label.tooltip = save_state == "conflict"
+                                 ? "Scene file changed outside Faset. Use Save As to keep both "
+                                   "versions, then compare or reload. " + save_error
+                             : save_state == "failed"
+                                 ? "Scene save failed. Your recovery journal remains available. "
+                                   "Use Save As or correct the error. " + save_error
+                             : save_state == "save_as_required"
+                                 ? "Choose Save As; unnamed scenes remain in recovery only"
+                             : save_state == "disabled"
+                                 ? "Autosave is off in Project settings; use Save manually"
+                                 : "Scene autosave status";
+        ui.find("autosave-save-as")->visible =
+            save_state == "conflict" || save_state == "failed" ||
+            save_state == "save_as_required";
         ui.find("renderer-status")->text =
             "Vulkan 1.3  |  " + std::to_string(resolved.at("entities").size()) + " objects";
     }
@@ -2043,6 +2102,45 @@ struct EditorUI::Impl {
         trim_children(conflict_list, conflict_keep);
         auto& console = *ui.find("console-items");
         std::set<std::string> keep;
+        std::size_t shown_diagnostics{};
+        for (const auto& job : all_jobs) {
+            const auto id = job.at("id").get<std::string>();
+            const auto diagnostics = job.value("diagnostics", Json::array());
+            if (!diagnostics.is_array())
+                continue;
+            for (std::size_t index = 0; index < diagnostics.size() && shown_diagnostics < 60;
+                 ++index, ++shown_diagnostics) {
+                const auto& diagnostic = diagnostics[index];
+                const auto row_id = "diagnostic-" + id + "-" + std::to_string(index);
+                auto& row = console.add(Kind::Row, row_id);
+                row.layout.height = 27;
+                row.layout.gap = 8;
+                keep.insert(row_id);
+                const auto severity = diagnostic.value("severity", std::string("error"));
+                label(row, row_id + "-severity", severity, 68);
+                auto message = diagnostic.value("message", std::string());
+                auto& detail = row.add(Kind::Label, row_id + "-message", message);
+                detail.layout.flex = 1;
+                detail.tooltip = diagnostic.value("phase", std::string()) + ": " + message;
+                const auto file = diagnostic.value("file", std::string());
+                const auto line = diagnostic.value("line", 1);
+                const auto column = diagnostic.value("column", 1);
+                const auto location = file.empty()
+                                          ? std::string("—")
+                                          : file + ":" + std::to_string(line) + ":" +
+                                                std::to_string(column);
+                label(row, row_id + "-location", location, 235);
+                auto& open = button(
+                    row, row_id + "-open", "Open source",
+                    [this, file, line, column] {
+                        call("faset_source_open",
+                             {{"path", file}, {"line", line}, {"column", column}});
+                    },
+                    115);
+                open.enabled = !file.empty();
+                open.appearance = ui::Appearance::Quiet;
+            }
+        }
         const auto& logs = session.logs();
         for (std::size_t i = logs.size() > 150 ? logs.size() - 150 : 0; i < logs.size(); ++i) {
             std::string line = logs[i];
@@ -2065,11 +2163,25 @@ struct EditorUI::Impl {
             row.layout.height = 28;
             keep.insert(row.id);
             const auto state = job.value("state", std::string());
+            const auto result = job.value("result", Json::object());
+            std::string reuse;
+            if (result.is_object() && result.value("schema_cache_hit", false))
+                reuse = " · verified reuse";
+            if (result.is_object() && result.contains("phase_times_ms") &&
+                result.at("phase_times_ms").is_object())
+                reuse += " · " +
+                         std::to_string(result.at("phase_times_ms").value("total", 0)) + " ms";
             auto& text = row.add(Kind::Label, "job-text-" + id,
                                  job.value("kind", std::string("Job")) + " · " + state + " · " +
                                      job.value("stage", std::string()) + " " +
-                                     std::to_string(int(job.value("progress", 0.0) * 100)) + "%");
+                                     std::to_string(int(job.value("progress", 0.0) * 100)) + "%" +
+                                     reuse);
             text.layout.flex = 1;
+            auto& log_button = button(
+                row, "job-log-toggle-" + id,
+                expanded_job_log == id ? "Hide log" : "View log",
+                [this, id] { expanded_job_log = expanded_job_log == id ? "" : id; }, 86);
+            log_button.appearance = ui::Appearance::Quiet;
             auto& cancel = button(
                 row, "job-cancel-" + id, "Cancel",
                 [this, id] { call("faset_job_cancel", {{"id", id}}); }, 72);
@@ -2078,6 +2190,38 @@ struct EditorUI::Impl {
                 row, "job-review-" + id, "Review removals", [this] { active_bottom = "conflicts"; },
                 135);
             review.visible = job.value("kind", std::string()) == "import" && state == "conflict";
+            if (expanded_job_log == id) {
+                const auto panel_id = "job-log-panel-" + id;
+                auto& panel = jobs.add(Kind::Column, panel_id);
+                panel.layout.height = 170;
+                panel.layout.scroll = true;
+                panel.layout.gap = 1;
+                keep.insert(panel_id);
+                std::set<std::string> log_keep;
+                const auto raw = job.value("log", std::string());
+                auto& copy = button(panel, panel_id + "-copy", "Copy full log",
+                                    [this, raw] { renderer.set_clipboard(raw); }, 110);
+                copy.appearance = ui::Appearance::Quiet;
+                log_keep.insert(copy.id);
+                std::vector<std::string> lines;
+                std::size_t begin{};
+                while (begin < raw.size()) {
+                    const auto end = raw.find('\n', begin);
+                    lines.push_back(raw.substr(begin, end == std::string::npos
+                                                         ? std::string::npos
+                                                         : end - begin));
+                    if (end == std::string::npos)
+                        break;
+                    begin = end + 1;
+                }
+                const auto first = lines.size() > 100 ? lines.size() - 100 : 0;
+                for (std::size_t index = first; index < lines.size(); ++index) {
+                    const auto line_id = panel_id + "-line-" + std::to_string(index);
+                    label(panel, line_id, lines[index].substr(0, 600));
+                    log_keep.insert(line_id);
+                }
+                trim_children(panel, log_keep);
+            }
         }
         if (keep.empty()) {
             label(jobs, "jobs-empty", "No active import, build or export jobs.");
@@ -2094,7 +2238,7 @@ struct EditorUI::Impl {
         refresh_project_settings();
         const bool modal = palette || !recovery.empty() || simulation_open ||
                            project_switch_warning || project_settings_open;
-        for (const auto* id : {"menubar", "toolbar", "workspace", "bottom_panel"})
+        for (const auto* id : {"menubar", "toolbar", "workspace", "bottom_panel", "statusbar"})
             ui.find(id)->enabled = !modal;
         const bool file = menu == "File" || menu == "Faset",
                    edit = menu == "Edit" || menu == "Scene",
@@ -2149,6 +2293,8 @@ struct EditorUI::Impl {
         project_settings_state = result;
         const auto& settings = result.at("settings");
         project_settings_dimension = settings.value("dimension", 3);
+        project_settings_autosave = settings.at("editor").at("autosave").get<bool>();
+        ui.find("project-settings-autosave")->checked = project_settings_autosave;
         ui.update_text("project-settings-name", settings.value("name", std::string()), true);
         ui.update_text("project-settings-start", settings.value("start_scene", std::string()),
                        true);
@@ -2215,7 +2361,9 @@ struct EditorUI::Impl {
             project_settings_error = "Enter a project name.";
             return;
         }
-        Json changes = {{"name", name}, {"dimension", project_settings_dimension}};
+        Json changes = {{"name", name},
+                        {"dimension", project_settings_dimension},
+                        {"editor", {{"autosave", project_settings_autosave}}}};
         if (!start.empty() ||
             !project_settings_state.at("settings").value("start_scene", std::string()).empty())
             changes["start_scene"] = start;
@@ -2229,7 +2377,7 @@ struct EditorUI::Impl {
         project_settings_state = result;
         project_settings_open = false;
         project_settings_error.clear();
-        status = "Project settings saved for the next project open";
+        status = "Project settings saved; autosave preference applies now";
     }
     void refresh_project_settings() {
         auto* panel = ui.find("project-settings-panel");
@@ -2240,6 +2388,7 @@ struct EditorUI::Impl {
         panel->layout.y = std::max(0.f, (logical_height() - panel->layout.height) * .5f);
         ui.find("project-settings-2d")->selected = project_settings_dimension == 2;
         ui.find("project-settings-3d")->selected = project_settings_dimension == 3;
+        ui.find("project-settings-autosave")->checked = project_settings_autosave;
         ui.find("project-settings-error")->text = project_settings_error;
         for (auto& choice : ui.find("project-settings-scenes")->children)
             if (choice->kind == Kind::TreeRow)

src/editor/session.cpp

@@ -2,6 +2,7 @@
 #include <chrono>
 #include <faset/core/hash.hpp>
 #include <faset/core/io.hpp>
+#include <faset/editor/build_cache.hpp>
 #include <faset/editor/session.hpp>
 #include <faset/scripting/project.hpp>
 
@@ -22,6 +23,52 @@ BuildConfig build_config(const SessionConfig& config) {
     result.cache_root = config.project_root / ".faset/cache";
     return result;
 }
+struct ProjectState {
+    Json value;
+    std::string revision;
+};
+ProjectState read_project_state(const std::filesystem::path& project_root) {
+    const auto path = project_root / "project.faset.json";
+    if (std::filesystem::exists(path)) {
+        auto value = read_json(path);
+        // The revision represents persisted content, including whether a
+        // default-valued setting was explicitly written by another client.
+        const auto revision = sha256(value.dump());
+        require(value.is_object() && value.value("format", "") == "faset.project" &&
+                    value.value("version", 0) == 1,
+                "project.version", "Unsupported project format or version");
+        require(value.contains("name") && value.at("name").is_string() &&
+                    !value.at("name").get<std::string>().empty(),
+                "project.name", "Project name must be a nonempty string");
+        const auto dimension = value.value("dimension", 3);
+        require(dimension == 2 || dimension == 3, "project.dimension",
+                "Project dimension must be 2 or 3");
+        if (value.contains("start_scene")) {
+            require(value.at("start_scene").is_string(), "project.start_scene",
+                    "Project start_scene must be a relative path");
+            const auto scene = value.at("start_scene").get<std::string>();
+            if (!scene.empty())
+                project_path(project_root, path_from_utf8(scene));
+        }
+        if (value.contains("editor"))
+            require(value.at("editor").is_object(), "project.editor",
+                    "Project editor settings must be an object");
+        else
+            value["editor"] = Json::object();
+        if (value["editor"].contains("autosave"))
+            require(value["editor"]["autosave"].is_boolean(), "project.autosave",
+                    "Project autosave setting must be true or false");
+        else
+            value["editor"]["autosave"] = true;
+        return {std::move(value), revision};
+    }
+    Json value = {{"format", "faset.project"},
+                  {"version", 1},
+                  {"name", path_to_utf8(project_root.filename())},
+                  {"dimension", 3},
+                  {"editor", {{"autosave", true}}}};
+    return {value, sha256(value.dump())};
+}
 Json resolved_or_throw(Commands& commands, const std::string& id) {
     const auto resolved = commands.resolved_scene(id);
     if (!resolved.at("conflicts").empty())
@@ -51,7 +98,13 @@ struct Session::ImportTask {
 };
 Session::Session(SessionConfig config)
     : config_(std::move(config)), authoring_(config_.project_root), commands_(authoring_),
-      assets_(config_.project_root / ".faset/cache"), builds_(build_config(config_)) {
+      assets_(config_.project_root / ".faset/cache"), builds_(build_config(config_)),
+      autosave_([this](const std::string& document, std::uint64_t revision) {
+          return authoring_.save(document, {}, revision);
+      }) {
+    autosave_enabled_ = project().at("editor").at("autosave").get<bool>();
+    autosave_.observe(authoring_.documents(), AutosaveController::Clock::now(),
+                      autosave_enabled_);
     register_commands();
     plugins_ = std::make_unique<PluginManager>(
         commands_, [this](std::string message) { log(std::move(message)); });
@@ -82,36 +135,16 @@ void Session::log(std::string value) {
         logs_.erase(logs_.begin(), logs_.begin() + 100);
 }
 Json Session::project() const {
-    const auto path = config_.project_root / "project.faset.json";
-    if (std::filesystem::exists(path)) {
-        const auto value = read_json(path);
-        require(value.is_object() && value.value("format", "") == "faset.project" &&
-                    value.value("version", 0) == 1,
-                "project.version", "Unsupported project format or version");
-        require(value.contains("name") && value.at("name").is_string() &&
-                    !value.at("name").get<std::string>().empty(),
-                "project.name", "Project name must be a nonempty string");
-        const auto dimension = value.value("dimension", 3);
-        require(dimension == 2 || dimension == 3, "project.dimension",
-                "Project dimension must be 2 or 3");
-        if (value.contains("start_scene")) {
-            require(value.at("start_scene").is_string(), "project.start_scene",
-                    "Project start_scene must be a relative path");
-            const auto scene = value.at("start_scene").get<std::string>();
-            if (!scene.empty())
-                project_path(config_.project_root, path_from_utf8(scene));
-        }
-        return value;
-    }
-    return {{"format", "faset.project"},
-            {"version", 1},
-            {"name", path_to_utf8(config_.project_root.filename())},
-            {"dimension", 3}};
+    return read_project_state(config_.project_root).value;
 }
 void Session::scaffold(const std::string& name, int dimension) {
     builds_.scaffold(name, dimension);
     log("Created project: " + name);
 }
+void Session::scaffold(const std::string& name, int dimension, std::string_view language) {
+    builds_.scaffold(name, dimension, language);
+    log("Created " + std::string(language) + " starter project: " + name);
+}
 Json Session::assets_list() const {
     Json list = Json::array();
     const auto directory = assets_.cache_root() / "assets";
@@ -132,20 +165,7 @@ Json Session::assets_list() const {
 }
 std::string Session::source_signature() const {
     const auto lua = scripting::loadLuaProject(config_.project_root);
-    const auto directory = config_.project_root / "Scripts";
-    std::vector<std::filesystem::path> files;
-    if (std::filesystem::exists(directory))
-        for (const auto& file : std::filesystem::recursive_directory_iterator(directory))
-            if (file.is_regular_file() && (!lua.enabled() || file.path().extension() != ".lua"))
-                files.push_back(file.path());
-    std::sort(files.begin(), files.end());
-    std::string contents;
-    for (const auto& file : files)
-        contents += generic_path_to_utf8(file.lexically_relative(directory)) + ":" +
-                    sha256_file(file) + "\n";
-    if (lua.enabled())
-        contents += "lua:" + lua.fingerprint + "\n";
-    return sha256(contents);
+    return gameplay_source_hash(config_.project_root, lua);
 }
 Json Session::schema_status() const {
     try {
@@ -305,12 +325,19 @@ void Session::poll() {
         if (status == "failed" || status == "conflict")
             log("Asset import " + status + ": " + value.value("error", std::string()));
     }
+    autosave_.observe(authoring_.documents(), AutosaveController::Clock::now(),
+                      autosave_enabled_);
 }
 void Session::register_commands() {
     const Json text = {{"type", "string"}}, boolean = {{"type", "boolean"}};
     auto schema = [](Json properties, Json required = Json::array()) {
         return Commands::object_schema(std::move(properties), std::move(required));
     };
+    commands_.add("faset_autosave_status",
+                  "Read revision-aware scene autosave state. Unnamed scenes remain in recovery "
+                  "until explicitly saved with a path.",
+                  schema(Json::object()),
+                  [this](const Json&) { return autosave_.status(); }, true);
     commands_.add(
         "faset_capabilities", "Inspect available Editor services and rendering capabilities.",
         schema(Json::object()),
@@ -344,23 +371,25 @@ void Session::register_commands() {
         "faset_project_settings_get", "Read project settings and their content revision.",
         schema(Json::object()),
         [&](const Json&) {
-            const auto value = project();
-            return Json{{"settings", value}, {"revision", sha256(value.dump())}};
+            const auto state = read_project_state(config_.project_root);
+            return Json{{"settings", state.value}, {"revision", state.revision}};
         },
         true);
     commands_.add(
         "faset_project_settings_set",
-        "Save project name, initial scene dimension or start scene with an expected content "
-        "revision. Applies on the next project open; does not change the active scene or its Undo "
-        "history.",
+        "Save project name, initial scene dimension, start scene or editor.autosave with an "
+        "expected content revision. Autosave applies immediately; other settings apply on the "
+        "next project open without changing scene Undo history.",
         schema({{"revision", text}, {"settings", {{"type", "object"}}}}, {"revision", "settings"}),
         [&](const Json& args) {
-            auto value = project();
-            require(args.at("revision") == sha256(value.dump()), "revision.conflict",
+            auto state = read_project_state(config_.project_root);
+            auto value = std::move(state.value);
+            require(args.at("revision") == state.revision, "revision.conflict",
                     "Project settings changed; reload them before saving");
             const auto& changes = args.at("settings");
             for (const auto& [key, field] : changes.items()) {
-                require(key == "name" || key == "dimension" || key == "start_scene",
+                require(key == "name" || key == "dimension" || key == "start_scene" ||
+                            key == "editor",
                         "project.setting", "Unknown editable project setting: " + key);
                 if (key == "name")
                     require(field.is_string() && !field.get<std::string>().empty(), "project.name",
@@ -368,7 +397,15 @@ void Session::register_commands() {
                 else if (key == "dimension")
                     require(field.is_number_integer() && (field == 2 || field == 3),
                             "project.dimension", "Initial scene dimension must be 2 or 3");
-                else {
+                else if (key == "editor") {
+                    require(field.is_object() && field.size() == 1 &&
+                                field.contains("autosave"),
+                            "project.setting", "Only editor.autosave can be changed here");
+                    require(field.at("autosave").is_boolean(), "project.autosave",
+                            "Autosave must be enabled or disabled");
+                    value["editor"]["autosave"] = field.at("autosave");
+                    continue;
+                } else {
                     require(field.is_string() && !field.get<std::string>().empty(),
                             "project.start_scene", "Choose a saved scene inside the project");
                     const auto file = project_path(config_.project_root,
@@ -386,7 +423,10 @@ void Session::register_commands() {
             if (!value.contains("id"))
                 value["id"] = new_id();
             atomic_write_json(config_.project_root / "project.faset.json", value);
-            log("Project settings saved; changes apply on next project open");
+            autosave_enabled_ = value.at("editor").at("autosave").get<bool>();
+            autosave_.observe(authoring_.documents(), AutosaveController::Clock::now(),
+                              autosave_enabled_);
+            log("Project settings saved; autosave preference applies immediately");
             return Json{{"settings", value}, {"revision", sha256(value.dump())}};
         });
     commands_.add(
@@ -514,51 +554,102 @@ void Session::register_commands() {
                         {"configuration_created", create_configuration},
                         {"scripts_configuration_created", create_scripts_configuration}};
         });
-    commands_.add(
-        "faset_script_open",
-        "Open a project Lua source in an external editor, never as an executable. Optional editor "
-        "is an argv array (default: project editor.script_editor, then zed). Exact {file} and "
-        "{project} arguments are replaced; no shell expansion is performed.",
-        schema({{"path", text}, {"editor", {{"type", "array"}, {"items", text}, {"minItems", 1}}}},
-               {"path"}),
-        [&](const Json& args) {
-            const auto file = project_path(config_.project_root,
-                                           path_from_utf8(args.at("path").get<std::string>()));
-            require(file.extension() == ".lua" && std::filesystem::is_regular_file(file),
-                    "lua.source", "Select an existing .lua file inside the project");
-            Json command = Json::array({"zed", "{file}"});
-            const auto settings = project();
-            if (settings.contains("editor") && settings.at("editor").is_object() &&
-                settings.at("editor").contains("script_editor"))
-                command = settings.at("editor").at("script_editor");
-            if (args.contains("editor"))
-                command = args.at("editor");
-            require(command.is_array() && !command.empty(), "lua.editor",
-                    "Configure editor.script_editor as a nonempty executable/argument array");
-            std::vector<std::string> arguments;
-            bool has_file = false;
-            for (const auto& part : command) {
-                require(part.is_string(), "lua.editor", "Editor arguments must be strings");
-                auto argument = part.get<std::string>();
-                require(argument.find('\0') == std::string::npos, "lua.editor",
-                        "Editor arguments cannot contain NUL");
-                if (argument == "{file}") {
-                    require(!arguments.empty(), "lua.editor", "The first argument is the editor");
-                    argument = path_to_utf8(file);
-                    has_file = true;
-                } else if (argument == "{project}") {
-                    require(!arguments.empty(), "lua.editor", "The first argument is the editor");
-                    argument = path_to_utf8(std::filesystem::absolute(config_.project_root));
-                }
-                arguments.push_back(std::move(argument));
+    const auto open_source = [this](const Json& args, bool lua_only) -> Json {
+        const auto path_error = lua_only ? "lua.source" : "source.path";
+        const auto editor_error = lua_only ? "lua.editor" : "source.editor";
+        const auto requested = path_from_utf8(args.at("path").get<std::string>());
+        require(!requested.empty() && !requested.is_absolute(), path_error,
+                "Choose an existing source inside Scripts");
+        for (const auto& part : requested)
+            require(part != "..", path_error, "Source path cannot traverse outside Scripts");
+        std::filesystem::path file;
+        try {
+            file = project_path(config_.project_root, requested);
+        } catch (const std::exception&) {
+            throw Error(path_error, "Source path must stay inside project Scripts");
+        }
+        const auto project_root = std::filesystem::weakly_canonical(config_.project_root);
+        const auto relative = file.lexically_relative(project_root);
+        const auto name = generic_path_to_utf8(relative);
+        const auto extension = path_to_utf8(file.extension());
+        const bool supported = extension == ".cpp" || extension == ".hpp" ||
+                               extension == ".h" || extension == ".cc" ||
+                               extension == ".cxx" || extension == ".lua";
+        require(name.starts_with("Scripts/") && supported &&
+                    (!lua_only || extension == ".lua") &&
+                    std::filesystem::is_regular_file(file),
+                path_error, "Choose an existing source file inside Scripts");
+        const auto line = args.value("line", 1);
+        const auto column = args.value("column", 1);
+        require(line > 0 && column > 0, path_error, "Source line and column must be positive");
+        Json command = Json::array({"zed", "{file}:{line}:{column}"});
+        const auto settings = project();
+        if (settings.contains("editor") && settings.at("editor").is_object() &&
+            settings.at("editor").contains("script_editor"))
+            command = settings.at("editor").at("script_editor");
+        if (args.contains("editor"))
+            command = args.at("editor");
+        require(command.is_array() && !command.empty(), editor_error,
+                "Configure editor.script_editor as a nonempty executable/argument array");
+        auto replace = [](std::string& target, std::string_view token,
+                          const std::string& replacement) {
+            bool found = false;
+            std::size_t position = 0;
+            while ((position = target.find(token, position)) != std::string::npos) {
+                target.replace(position, token.size(), replacement);
+                position += replacement.size();
+                found = true;
             }
-            require(!arguments.front().empty(), "lua.editor", "Choose an editor executable");
-            if (!has_file)
-                arguments.push_back(path_to_utf8(file));
+            return found;
+        };
+        std::vector<std::string> arguments;
+        bool has_file = false;
+        for (const auto& part : command) {
+            require(part.is_string(), editor_error, "Editor arguments must be strings");
+            auto argument = part.get<std::string>();
+            require(argument.find('\0') == std::string::npos, editor_error,
+                    "Editor arguments cannot contain NUL");
+            if (arguments.empty())
+                require(!argument.empty() && argument.find('{') == std::string::npos,
+                        editor_error, "The first argument must be an editor executable");
+            else {
+                has_file |= replace(argument, "{file}", path_to_utf8(file));
+                replace(argument, "{line}", std::to_string(line));
+                replace(argument, "{column}", std::to_string(column));
+                replace(argument, "{project}", path_to_utf8(project_root));
+            }
+            arguments.push_back(std::move(argument));
+        }
+        if (!has_file)
+            arguments.push_back(path_to_utf8(file));
+        try {
             launch_detached(arguments, config_.project_root);
-            log("Opened Lua source in external editor: " + args.at("path").get<std::string>());
-            return Json{{"opened", args.at("path")}};
-        });
+        } catch (const std::exception& error) {
+            throw Error(editor_error, "Could not launch external source editor",
+                        {{"reason", error.what()}});
+        }
+        log("Opened source in external editor: " + name);
+        return {{"opened", name}, {"path", name}, {"line", line}, {"column", column}};
+    };
+    const auto source_schema = schema(
+        {{"path", text},
+         {"line", {{"type", "integer"}, {"minimum", 1}}},
+         {"column", {{"type", "integer"}, {"minimum", 1}}},
+         {"editor", {{"type", "array"}, {"items", text}, {"minItems", 1}}}},
+        {"path"});
+    commands_.add("faset_source_open",
+                  "Open a C++ or Lua source under Scripts at a one-based line and column. "
+                  "The editor is an argv array; {file}, {line}, {column} and {project} are "
+                  "substituted without a shell.",
+                  source_schema, [open_source](const Json& args) {
+                      return open_source(args, false);
+                  });
+    commands_.add("faset_script_open",
+                  "Open a project Lua source in an external editor. This compatibility command "
+                  "retains Lua-only validation and uses the same safe source launcher.",
+                  source_schema, [open_source](const Json& args) {
+                      return open_source(args, true);
+                  });
     commands_.add("faset_export",
                   "Build, validate and export a resolved authoring snapshot to a project-relative "
                   "output directory. Returns a job ID.",

src/player/SceneView.cpp

@@ -61,16 +61,6 @@ render::Vec3 direction(const render::Mat4& m, render::Vec3 p) {
     return {m[0] * p[0] + m[4] * p[1] + m[8] * p[2], m[1] * p[0] + m[5] * p[1] + m[9] * p[2],
             m[2] * p[0] + m[6] * p[1] + m[10] * p[2]};
 }
-render::Vec3 normalized(render::Vec3 value, const std::string& entityId,
-                        std::string_view field) {
-    const auto length = std::hypot(value[0], value[1], value[2]);
-    if (!std::isfinite(length) || length < 1e-6f)
-        throw std::invalid_argument("Light on entity " + entityId + " has invalid " +
-                                    std::string(field));
-    for (auto& axis : value)
-        axis /= length;
-    return value;
-}
 std::pair<std::string, std::string> reference(const std::string& ref) {
     const auto hash = ref.find('#');
     return {ref.substr(0, hash), hash == std::string::npos ? std::string{} : ref.substr(hash + 1)};
@@ -273,12 +263,8 @@ render::Snapshot SceneView::build(const Json& scene, float aspect, CameraSetting
         const auto id = entity.at("id").get<std::string>();
         if (!byId.emplace(id, &entity).second)
             throw std::invalid_argument("Duplicate scene ID");
-        if (!entity.contains("components") && entity.contains("light"))
-            out.authored_lights_present = true;
         for (const auto& component : entity.value("components", Json::array())) {
             const auto type = component.at("type").get<std::string>();
-            if (type == "faset.light")
-                out.authored_lights_present = true;
             if (component.value("version", 1) != 1 &&
                 (type == "faset.transform" || type == "faset.sprite" || type == "faset.mesh" ||
                  type == "faset.camera" || type == "faset.light"))
@@ -315,15 +301,8 @@ render::Snapshot SceneView::build(const Json& scene, float aspect, CameraSetting
     render::Vec3 cameraUp{0, 1, 0};
     bool foundCamera = false;
     std::vector<std::pair<int, render::Sprite>> sprites;
-    std::vector<render::SunLight> directionalLights;
     for (const auto& entity : entities) {
-        const auto id = entity.at("id").get<std::string>();
-        render::Mat4 model;
-        try {
-            model = world(world, entity);
-        } catch (const std::exception& error) {
-            throw std::invalid_argument("Entity " + id + " transform: " + error.what());
-        }
+        const auto model = world(world, entity);
         if (auto fields = properties(entity, "camera");
             !fields.is_null() && !camera.overrideSceneCamera && !foundCamera) {
             camera.eye = point(model, {0, 0, 0});
@@ -335,97 +314,8 @@ render::Snapshot SceneView::build(const Json& scene, float aspect, CameraSetting
             foundCamera = true;
             camera_id = entity.at("id").get<std::string>();
         }
-        if (auto fields = properties(entity, "light"); !fields.is_null()) {
-            auto invalid = [&](std::string_view field) -> void {
-                throw std::invalid_argument("Light on entity " + id + " has invalid " +
-                                            std::string(field));
-            };
-            for (const auto entry : model)
-                if (!std::isfinite(entry))
-                    invalid("transform");
-            auto number = [&](const char* field, float fallback) {
-                if (!fields.contains(field))
-                    return fallback;
-                const auto& value = fields.at(field);
-                if (!value.is_number())
-                    invalid(field);
-                const auto decimal = value.get<double>();
-                if (!std::isfinite(decimal) ||
-                    std::abs(decimal) > std::numeric_limits<float>::max())
-                    invalid(field);
-                return static_cast<float>(decimal);
-            };
-            auto boolean = [&](const char* field, bool fallback) {
-                if (!fields.contains(field))
-                    return fallback;
-                if (!fields.at(field).is_boolean())
-                    invalid(field);
-                return fields.at(field).get<bool>();
-            };
-            const auto enabled = boolean("enabled", true);
-            if (enabled) {
-                if (fields.contains("kind") && !fields.at("kind").is_string())
-                    invalid("kind");
-                const auto kind = fields.value("kind", std::string("directional"));
-                if (kind != "directional" && kind != "point" && kind != "spot")
-                    invalid("kind");
-                render::Color color;
-                try {
-                    color = vec<4>(fields, "color", {1, 1, 1, 1});
-                } catch (const std::exception&) {
-                    invalid("color");
-                }
-                for (const auto channel : color)
-                    if (channel < 0)
-                        invalid("color");
-                const auto intensity = number("intensity", 1);
-                if (intensity < 0)
-                    invalid("intensity");
-                const auto castsShadow = boolean("casts_shadow", true);
-                const auto stableId = id;
-                if (kind == "directional") {
-                    directionalLights.push_back({stableId,
-                                                 normalized(direction(model, {-0.5f, -1, -0.3f}), id,
-                                                            "direction"),
-                                                 color, intensity, castsShadow});
-                } else {
-                    render::LocalLight local;
-                    local.kind = kind == "point" ? render::LocalLight::Kind::Point
-                                                 : render::LocalLight::Kind::Spot;
-                    local.stable_id = stableId;
-                    local.position = point(model, {0, 0, 0});
-                    for (const auto coordinate : local.position)
-                        if (!std::isfinite(coordinate))
-                            invalid("position");
-                    if (local.kind == render::LocalLight::Kind::Spot)
-                        local.direction = normalized(direction(model, {0, 0, -1}), id,
-                                                     "direction");
-                    local.color = color;
-                    local.intensity = intensity;
-                    local.range = number("range", 10);
-                    if (local.range <= 0)
-                        invalid("range");
-                    local.inner_angle = number("inner_angle", 0.35f);
-                    local.outer_angle = number("outer_angle", 0.7f);
-                    if (local.kind == render::LocalLight::Kind::Spot &&
-                        (local.inner_angle < 0 || local.inner_angle > local.outer_angle ||
-                         local.outer_angle <= 0 ||
-                         local.outer_angle >= std::numbers::pi_v<float> / 2))
-                        invalid("inner_angle/outer_angle");
-                    local.casts_shadow = castsShadow;
-                    if (fields.contains("shadow_priority")) {
-                        if (!fields.at("shadow_priority").is_number_integer())
-                            invalid("shadow_priority");
-                        const auto priority = fields.at("shadow_priority").get<double>();
-                        if (priority < std::numeric_limits<int>::min() ||
-                            priority > std::numeric_limits<int>::max())
-                            invalid("shadow_priority");
-                        local.shadow_priority = fields.at("shadow_priority").get<int>();
-                    }
-                    out.local_lights.push_back(std::move(local));
-                }
-            }
-        }
+        if (auto fields = properties(entity, "light"); !fields.is_null())
+            out.light_direction = direction(model, {-0.5f, -1, -0.3f});
         if (auto fields = properties(entity, "sprite"); !fields.is_null()) {
             render::Sprite sprite;
             sprite.layer = fields.value("layer", 0);
@@ -482,18 +372,6 @@ render::Snapshot SceneView::build(const Json& scene, float aspect, CameraSetting
                      [](const auto& a, const auto& b) { return a.first < b.first; });
     for (auto& pair : sprites)
         out.sprites.push_back(std::move(pair.second));
-    std::sort(directionalLights.begin(), directionalLights.end(),
-              [](const auto& a, const auto& b) { return a.stable_id < b.stable_id; });
-    std::sort(out.local_lights.begin(), out.local_lights.end(),
-              [](const auto& a, const auto& b) { return a.stable_id < b.stable_id; });
-    if (!directionalLights.empty()) {
-        out.sun = directionalLights.front();
-        out.light_direction = out.sun->direction;
-        if (directionalLights.size() > 1)
-            impl_->messages.push_back("warning: multiple enabled directional lights; using " +
-                                      out.sun->stable_id + " and ignoring " +
-                                      std::to_string(directionalLights.size() - 1) + " others");
-    }
     if (dimension == 2) {
         const float height = camera.orthographicHeight;
         if (!std::isfinite(height) || height <= 0)
@@ -530,10 +408,8 @@ render::Snapshot SceneView::build(const Json& scene, float aspect, CameraSetting
         out.projection = render::perspective(
             camera.verticalFovDegrees * std::numbers::pi_v<float> / 180, aspect,
             camera.nearPlane, camera.farPlane);
-        const auto view = render::look_at(camera.eye, camera.target, cameraUp);
-        out.view_projection = render::multiply(out.projection, view);
-        out.camera_frustum = render::CameraFrustum{view, out.projection, camera.nearPlane,
-                                                   camera.farPlane, true};
+        out.view_projection = render::multiply(
+            out.projection, render::look_at(camera.eye, camera.target, cameraUp));
     }
     std::sort(impl_->messages.begin(), impl_->messages.end());
     impl_->messages.erase(std::unique(impl_->messages.begin(), impl_->messages.end()),

src/render/lighting.cpp

@@ -1,394 +0,0 @@
-#include <faset/render/lighting.hpp>
-#include <algorithm>
-#include <array>
-#include <cmath>
-#include <limits>
-#include <numbers>
-#include <stdexcept>
-#include <unordered_set>
-
-namespace faset::render {
-namespace {
-Vec3 add(Vec3 a, Vec3 b) { return {a[0] + b[0], a[1] + b[1], a[2] + b[2]}; }
-Vec3 subtract(Vec3 a, Vec3 b) { return {a[0] - b[0], a[1] - b[1], a[2] - b[2]}; }
-Vec3 scale(Vec3 a, float factor) { return {a[0] * factor, a[1] * factor, a[2] * factor}; }
-float dot(Vec3 a, Vec3 b) { return a[0] * b[0] + a[1] * b[1] + a[2] * b[2]; }
-float length(Vec3 a) { return std::sqrt(dot(a, a)); }
-Vec3 unit(Vec3 a) {
-    const float magnitude = length(a);
-    if (!std::isfinite(magnitude) || magnitude < 1e-6f)
-        throw std::invalid_argument("Shadow light direction must be finite and nonzero");
-    return scale(a, 1.f / magnitude);
-}
-Vec3 project(const Mat4& matrix, Vec3 value) {
-    return {matrix[0] * value[0] + matrix[4] * value[1] + matrix[8] * value[2] + matrix[12],
-            matrix[1] * value[0] + matrix[5] * value[1] + matrix[9] * value[2] + matrix[13],
-            matrix[2] * value[0] + matrix[6] * value[1] + matrix[10] * value[2] + matrix[14]};
-}
-std::array<float, 4> clip(const Mat4& matrix, Vec3 value) {
-    return {matrix[0] * value[0] + matrix[4] * value[1] + matrix[8] * value[2] + matrix[12],
-            matrix[1] * value[0] + matrix[5] * value[1] + matrix[9] * value[2] + matrix[13],
-            matrix[2] * value[0] + matrix[6] * value[1] + matrix[10] * value[2] + matrix[14],
-            matrix[3] * value[0] + matrix[7] * value[1] + matrix[11] * value[2] + matrix[15]};
-}
-std::array<Vec3, 8> corners(const Bounds& bounds) {
-    std::array<Vec3, 8> result{};
-    for (unsigned i = 0; i < 8; ++i)
-        result[i] = {i & 1 ? bounds.max[0] : bounds.min[0],
-                     i & 2 ? bounds.max[1] : bounds.min[1],
-                     i & 4 ? bounds.max[2] : bounds.min[2]};
-    return result;
-}
-Vec3 camera_to_world(const Mat4& view, Vec3 camera) {
-    // CameraFrustum::view is an unscaled, orthonormal look_at matrix.
-    return {view[0] * (camera[0] - view[12]) + view[1] * (camera[1] - view[13]) +
-                view[2] * (camera[2] - view[14]),
-            view[4] * (camera[0] - view[12]) + view[5] * (camera[1] - view[13]) +
-                view[6] * (camera[2] - view[14]),
-            view[8] * (camera[0] - view[12]) + view[9] * (camera[1] - view[13]) +
-                view[10] * (camera[2] - view[14])};
-}
-std::array<Vec3, 8> frustum_slice(const CameraFrustum& camera, float near_distance,
-                                  float far_distance) {
-    std::array<Vec3, 8> result{};
-    for (unsigned i = 0; i < 8; ++i) {
-        const float distance = i & 4 ? far_distance : near_distance;
-        const float x = i & 1 ? 1.f : -1.f;
-        const float y = i & 2 ? 1.f : -1.f;
-        Vec3 local{};
-        if (camera.perspective)
-            local = {x * distance / camera.projection[0],
-                     y * distance / camera.projection[5], -distance};
-        else
-            local = {(x - camera.projection[12]) / camera.projection[0],
-                     (y - camera.projection[13]) / camera.projection[5], -distance};
-        result[i] = camera_to_world(camera.view, local);
-    }
-    return result;
-}
-bool overlaps_xy(const Bounds& bounds, const Mat4& light_view, float left, float right,
-                 float bottom, float top) {
-    float min_x = std::numeric_limits<float>::infinity();
-    float max_x = -min_x, min_y = min_x, max_y = -min_x;
-    for (const auto point : corners(bounds)) {
-        const auto light = project(light_view, point);
-        min_x = std::min(min_x, light[0]);
-        max_x = std::max(max_x, light[0]);
-        min_y = std::min(min_y, light[1]);
-        max_y = std::max(max_y, light[1]);
-    }
-    return max_x >= left && min_x <= right && max_y >= bottom && min_y <= top;
-}
-bool intersects_frustum(const Bounds& bounds, const Mat4& view_projection) {
-    std::array<unsigned, 7> rejected{};
-    for (const auto point : corners(bounds)) {
-        const auto p = clip(view_projection, point);
-        if (!std::all_of(p.begin(), p.end(), [](float value) { return std::isfinite(value); }))
-            return true; // Invalid projection fails open so no caster is lost silently.
-        rejected[0] += p[0] < -p[3];
-        rejected[1] += p[0] > p[3];
-        rejected[2] += p[1] < -p[3];
-        rejected[3] += p[1] > p[3];
-        rejected[4] += p[2] < 0;
-        rejected[5] += p[2] > p[3];
-        rejected[6] += p[3] <= 0;
-    }
-    return std::none_of(rejected.begin(), rejected.end(), [](unsigned count) { return count == 8; });
-}
-void tile(ShadowView& view, std::uint32_t atlas_size, std::uint32_t tiles_across,
-          std::uint32_t index) {
-    constexpr std::uint32_t guard = 2;
-    const auto size = atlas_size / tiles_across;
-    view.tile_index = index;
-    view.tile_origin_x = (index % tiles_across) * size;
-    view.tile_origin_y = (index / tiles_across) * size;
-    view.tile_size = size;
-    view.usable_size = size - 2 * guard;
-    const auto reciprocal = 1.f / float(atlas_size);
-    view.atlas_scale_offset = {float(view.usable_size) * reciprocal,
-                               float(view.usable_size) * reciprocal,
-                               float(view.tile_origin_x + guard) * reciprocal,
-                               float(view.tile_origin_y + guard) * reciprocal};
-    view.guarded_clamp = {(float(view.tile_origin_x + guard) + 1.5f) * reciprocal,
-                          (float(view.tile_origin_y + guard) + 1.5f) * reciprocal,
-                          (float(view.tile_origin_x + size - guard) - 1.5f) * reciprocal,
-                          (float(view.tile_origin_y + size - guard) - 1.5f) * reciprocal};
-}
-std::vector<std::uint32_t> visible_casters(const Mat4& view_projection,
-                                           std::span<const ShadowCasterBounds> casters) {
-    std::vector<std::uint32_t> result;
-    for (const auto& caster : casters)
-        if (intersects_frustum(caster.world, view_projection))
-            result.push_back(caster.draw_index);
-    std::sort(result.begin(), result.end());
-    result.erase(std::unique(result.begin(), result.end()), result.end());
-    return result;
-}
-bool supported_atlas(std::uint32_t size, bool available) {
-    return available && (size == 2048 || size == 1024);
-}
-void validate_local(const LocalLight& light) {
-    const auto invalid = [&](const char* field) {
-        throw std::invalid_argument("Local light " + light.stable_id + " has invalid " + field);
-    };
-    if (light.stable_id.empty())
-        invalid("stable_id");
-    if (!std::all_of(light.position.begin(), light.position.end(),
-                     [](float v) { return std::isfinite(v); }))
-        invalid("position");
-    if (!std::all_of(light.color.begin(), light.color.end(),
-                     [](float v) { return std::isfinite(v) && v >= 0; }))
-        invalid("color");
-    if (!std::isfinite(light.intensity) || light.intensity < 0)
-        invalid("intensity");
-    if (!std::isfinite(light.range) || light.range <= 0)
-        invalid("range");
-    if (light.kind == LocalLight::Kind::Spot) {
-        if (!std::isfinite(light.inner_angle) || !std::isfinite(light.outer_angle) ||
-            light.inner_angle < 0 || light.inner_angle > light.outer_angle ||
-            light.outer_angle >= std::numbers::pi_v<float> / 2 || light.outer_angle <= 0)
-            invalid("inner_angle/outer_angle");
-        if (!std::all_of(light.direction.begin(), light.direction.end(),
-                         [](float v) { return std::isfinite(v); }) ||
-            length(light.direction) < 1e-6f)
-            invalid("direction");
-    }
-}
-float projected_influence(const LocalLight& light, const Snapshot& frame) {
-    const auto distance = length(subtract(light.position, frame.eye));
-    const auto projection_scale =
-        std::max(std::abs(frame.projection[0]), std::abs(frame.projection[5]));
-    return light.range * projection_scale / std::max(distance, .1f);
-}
-ShadowView sun_view(const Snapshot& frame, const SunLight& sun,
-                    std::span<const ShadowCasterBounds> casters, float split_near,
-                    float split_far, std::uint32_t index, std::uint32_t atlas_size) {
-    ShadowView result;
-    result.kind = ShadowView::Kind::Sun;
-    result.light_id = sun.stable_id;
-    result.face_index = index;
-    result.split_near = split_near;
-    result.split_far = split_far;
-    tile(result, atlas_size, 2, index);
-    const auto direction = unit(sun.direction);
-    const auto up = std::abs(direction[1]) > .98f ? Vec3{0, 0, 1} : Vec3{0, 1, 0};
-    const auto light_origin_view = look_at({0, 0, 0}, direction, up);
-    if (!frame.camera_frustum) {
-        const auto light_eye = scale(direction, -30);
-        result.view_projection = multiply(orthographic(-20, 20, -20, 20, .1f, 80),
-                                          look_at(light_eye, {0, 0, 0}, up));
-        result.caster_indices = visible_casters(result.view_projection, casters);
-        return result;
-    }
-    const auto receivers = frustum_slice(*frame.camera_frustum, split_near, split_far);
-    Vec3 center{};
-    for (const auto corner : receivers)
-        center = add(center, scale(corner, 1.f / 8));
-    float radius{};
-    for (const auto corner : receivers)
-        radius = std::max(radius, length(subtract(corner, center)));
-    radius = std::max(.25f, std::ceil(radius * 16.f) / 16.f);
-    const auto center_light = project(light_origin_view, center);
-    const auto texel = (2 * radius) / float(result.usable_size);
-    result.snapped_center_x = std::round(center_light[0] / texel) * texel;
-    result.snapped_center_y = std::round(center_light[1] / texel) * texel;
-    const float left = result.snapped_center_x - radius;
-    const float right = result.snapped_center_x + radius;
-    const float bottom = result.snapped_center_y - radius;
-    const float top = result.snapped_center_y + radius;
-    float nearest_ray = std::numeric_limits<float>::infinity();
-    float furthest_ray = -nearest_ray;
-    for (const auto corner : receivers) {
-        const auto ray = dot(corner, direction);
-        nearest_ray = std::min(nearest_ray, ray);
-        furthest_ray = std::max(furthest_ray, ray);
-    }
-    for (const auto& caster : casters) {
-        if (!overlaps_xy(caster.world, light_origin_view, left, right, bottom, top))
-            continue;
-        result.caster_indices.push_back(caster.draw_index);
-        for (const auto corner : corners(caster.world)) {
-            const auto ray = dot(corner, direction);
-            nearest_ray = std::min(nearest_ray, ray);
-            furthest_ray = std::max(furthest_ray, ray);
-        }
-    }
-    std::sort(result.caster_indices.begin(), result.caster_indices.end());
-    result.caster_indices.erase(
-        std::unique(result.caster_indices.begin(), result.caster_indices.end()),
-        result.caster_indices.end());
-    const auto light_eye = scale(direction, nearest_ray - 1.f);
-    const auto view = look_at(light_eye, add(light_eye, direction), up);
-    const auto depth = std::max(2.f, furthest_ray - nearest_ray + 2.f);
-    result.view_projection = multiply(orthographic(left, right, bottom, top, .1f, depth),
-                                      view);
-    return result;
-}
-ShadowView local_view(const LocalLight& light, std::uint32_t face,
-                      std::span<const ShadowCasterBounds> casters) {
-    ShadowView result;
-    result.kind = light.kind == LocalLight::Kind::Point ? ShadowView::Kind::Point
-                                                        : ShadowView::Kind::Spot;
-    result.light_id = light.stable_id;
-    result.face_index = face;
-    static constexpr std::array<Vec3, 6> axes{{{1, 0, 0}, {-1, 0, 0}, {0, 1, 0},
-                                                {0, -1, 0}, {0, 0, 1}, {0, 0, -1}}};
-    static constexpr std::array<Vec3, 6> ups{{{0, -1, 0}, {0, -1, 0}, {0, 0, 1},
-                                               {0, 0, -1}, {0, -1, 0}, {0, -1, 0}}};
-    const auto direction = light.kind == LocalLight::Kind::Point ? axes.at(face)
-                                                                 : unit(light.direction);
-    const auto up = light.kind == LocalLight::Kind::Point ? ups.at(face)
-                    : std::abs(direction[1]) > .98f ? Vec3{0, 0, 1} : Vec3{0, 1, 0};
-    const auto near_plane = std::max(.0001f, std::min(.05f, light.range * .1f));
-    // Slight face overlap keeps the dominant-axis choice inside both adjacent
-    // projections at a cubemap seam; the guarded tile still prevents PCF bleed.
-    const auto fov = light.kind == LocalLight::Kind::Point
-        ? std::numbers::pi_v<float> / 2 + .04f : light.outer_angle * 2;
-    result.view_projection = multiply(
-        perspective(fov, 1, near_plane, light.range),
-        look_at(light.position, add(light.position, direction), up));
-    result.caster_indices = visible_casters(result.view_projection, casters);
-    return result;
-}
-} // namespace
-
-ShadowPlan build_shadow_plan(const Snapshot& frame,
-                             std::span<const ShadowCasterBounds> casters,
-                             const ShadowBudget& budget) {
-    for (const auto& caster : casters)
-        for (int axis = 0; axis < 3; ++axis)
-            if (!std::isfinite(caster.world.min[axis]) ||
-                !std::isfinite(caster.world.max[axis]) ||
-                caster.world.min[axis] > caster.world.max[axis])
-                throw std::invalid_argument("Shadow caster world bounds must be finite and ordered");
-    ShadowPlan plan;
-    plan.sun_atlas_size = supported_atlas(budget.sun_atlas_size, budget.sun_atlas_available)
-        ? budget.sun_atlas_size : 0;
-    plan.local_atlas_size = supported_atlas(budget.local_atlas_size, budget.local_atlas_available)
-        ? budget.local_atlas_size : 0;
-    std::unordered_set<std::string> ids;
-    std::vector<std::pair<std::size_t, float>> ranked;
-    ranked.reserve(frame.local_lights.size());
-    for (std::size_t i = 0; i < frame.local_lights.size(); ++i) {
-        const auto& light = frame.local_lights[i];
-        validate_local(light); // Validate overflow records too, before truncation.
-        if (!ids.insert(light.stable_id).second)
-            throw std::invalid_argument("Duplicate local light stable_id: " + light.stable_id);
-        ranked.emplace_back(i, projected_influence(light, frame));
-    }
-    std::sort(ranked.begin(), ranked.end(), [&](const auto& a, const auto& b) {
-        const auto& left = frame.local_lights[a.first];
-        const auto& right = frame.local_lights[b.first];
-        if (left.shadow_priority != right.shadow_priority)
-            return left.shadow_priority > right.shadow_priority;
-        if (a.second != b.second)
-            return a.second > b.second;
-        return left.stable_id < right.stable_id;
-    });
-    const auto selected = std::min<std::size_t>(ranked.size(),
-                                                std::min(budget.max_local_lights, 128u));
-    plan.omitted_local_lights = static_cast<std::uint32_t>(ranked.size() - selected);
-    for (std::size_t i = 0; i < selected; ++i)
-        plan.submitted_local_indices.push_back(ranked[i].first);
-
-    std::optional<SunLight> sun = frame.sun;
-    if (!sun && !frame.authored_lights_present && frame.local_lights.empty())
-        sun = SunLight{"legacy-sun", frame.light_direction, {1, 1, 1, 1}, 1, true};
-    if (sun && sun->casts_shadow) {
-        plan.requested_sun_cascades = frame.camera_frustum
-            ? std::min(4u, budget.max_sun_views) : 1u;
-        if (frame.camera_frustum &&
-            (frame.camera_frustum->near_plane <= 0 ||
-             frame.camera_frustum->far_plane <= frame.camera_frustum->near_plane ||
-             frame.camera_frustum->projection[0] == 0 ||
-             frame.camera_frustum->projection[5] == 0))
-            throw std::invalid_argument("Shadow camera frustum is invalid");
-        const float near_plane = frame.camera_frustum ? frame.camera_frustum->near_plane : .1f;
-        const float far_plane = frame.camera_frustum
-            ? std::min(frame.camera_frustum->far_plane, budget.max_shadow_distance) : 80.f;
-        if (far_plane <= near_plane)
-            throw std::invalid_argument("Shadow distance does not reach the camera near plane");
-        float previous = near_plane;
-        for (std::uint32_t i = 0; i < plan.requested_sun_cascades; ++i) {
-            const auto ratio = float(i + 1) / float(plan.requested_sun_cascades);
-            const auto logarithmic = near_plane * std::pow(far_plane / near_plane, ratio);
-            const auto uniform = near_plane + (far_plane - near_plane) * ratio;
-            const auto split = i + 1 == plan.requested_sun_cascades
-                ? far_plane : .5f * (logarithmic + uniform);
-            ShadowView view;
-            if (plan.sun_atlas_size)
-                view = sun_view(frame, *sun, casters, previous, split, i, plan.sun_atlas_size);
-            else {
-                view.kind = ShadowView::Kind::Sun;
-                view.light_id = sun->stable_id;
-                view.face_index = i;
-                view.split_near = previous;
-                view.split_far = split;
-                view.reason = ShadowDropReason::Unavailable;
-            }
-            if (plan.sun_atlas_size &&
-                view.caster_indices.size() <=
-                    budget.max_caster_draws - std::min(plan.caster_draws, budget.max_caster_draws)) {
-                view.valid = true;
-                plan.caster_draws += static_cast<std::uint32_t>(view.caster_indices.size());
-                ++plan.effective_sun_cascades;
-            } else {
-                if (plan.sun_atlas_size)
-                    view.reason = ShadowDropReason::CasterBudget;
-                view.caster_indices.clear();
-                ++plan.dropped_sun_views;
-            }
-            plan.sun_views.push_back(std::move(view));
-            previous = split;
-        }
-    }
-    for (const auto source : plan.submitted_local_indices) {
-        const auto& light = frame.local_lights[source];
-        LocalShadowAssignment assignment;
-        assignment.source_index = source;
-        assignment.first_view = static_cast<std::uint32_t>(plan.local_views.size());
-        const auto faces = light.kind == LocalLight::Kind::Point ? 6u : 1u;
-        if (!light.casts_shadow || light.intensity == 0) {
-            plan.local_assignments.push_back(assignment);
-            continue;
-        }
-        plan.local_faces_requested += faces;
-        if (!plan.local_atlas_size)
-            assignment.reason = ShadowDropReason::Unavailable;
-        else if (const auto capacity = std::min(budget.max_local_faces, 16u);
-                 faces > capacity - std::min(plan.local_faces_used, capacity))
-            assignment.reason = ShadowDropReason::TileBudget;
-        else {
-            std::vector<ShadowView> group;
-            std::uint32_t group_draws{};
-            for (std::uint32_t face = 0; face < faces; ++face) {
-                auto view = local_view(light, face, casters);
-                tile(view, plan.local_atlas_size, 4,
-                     plan.local_faces_used + face);
-                group_draws += static_cast<std::uint32_t>(view.caster_indices.size());
-                group.push_back(std::move(view));
-            }
-            if (group_draws > budget.max_caster_draws -
-                                  std::min(plan.caster_draws, budget.max_caster_draws))
-                assignment.reason = ShadowDropReason::CasterBudget;
-            else {
-                assignment.valid = true;
-                assignment.face_count = faces;
-                plan.local_faces_used += faces;
-                plan.caster_draws += group_draws;
-                for (auto& view : group) {
-                    view.valid = true;
-                    plan.local_views.push_back(std::move(view));
-                }
-            }
-        }
-        if (!assignment.valid) {
-            plan.dropped_local_faces += faces;
-            if (light.kind == LocalLight::Kind::Point)
-                plan.dropped_point_faces += 6;
-        }
-        plan.local_assignments.push_back(assignment);
-    }
-    return plan;
-}
-} // namespace faset::render

src/render/shader_contract.cpp

@@ -30,64 +30,17 @@ void locations(const Json& fields, std::initializer_list<const char*> types, con
         ++index;
     }
 }
-void validate_tile_layout(const Json& layout) {
-    require(layout.at("stage") == "compute", "light tile shader stage changed");
-    const auto& descriptors = layout.at("descriptors");
-    require(descriptors.is_array() && descriptors.size() == 2,
-            "light tile descriptor count changed");
-    for (std::size_t i = 0; i < 2; ++i)
-        require(descriptors[i].at("set") == 0 && descriptors[i].at("binding") == i &&
-                    descriptors[i].at("count") == 1 &&
-                    descriptors[i].at("type") == "storage_buffer" &&
-                    descriptors[i].at("element_stride") == (i == 0 ? 80 : 4),
-                "light tile descriptor ABI changed");
-    const auto& constants = layout.at("push_constants");
-    require(constants.is_array() && constants.size() == 1 &&
-                constants[0].at("offset") == 0 && constants[0].at("size") == 96,
-            "light tile push size changed");
-    const auto& members = constants[0].at("members");
-    require(members.is_array() && members.size() == 3,
-            "light tile push members changed");
-    const int offsets[] = {0, 64, 80};
-    const char* types[] = {"float32x4x4", "float32x4", "uint32x4"};
-    for (std::size_t i = 0; i < 3; ++i)
-        require(members[i].at("offset") == offsets[i] &&
-                    members[i].at("size") == (i == 0 ? 64 : 16) &&
-                    members[i].at("type") == types[i],
-                "light tile push field changed");
-    const auto& blocks = layout.at("spirv_push_constants");
-    require(blocks.is_array() && blocks.size() == 1 &&
-                blocks[0].at("members").size() == 3,
-            "light tile SPIR-V push block changed");
-    const auto& actual = blocks[0].at("members");
-    for (std::size_t i = 0; i < 3; ++i)
-        require(actual[i].at("member") == i && actual[i].at("offset") == offsets[i],
-                "light tile SPIR-V push offset changed");
-    require(actual[0].at("matrix_layout") == "row-major" &&
-                actual[0].at("matrix_stride") == 16,
-            "light tile SPIR-V matrix storage convention changed");
-    locations(layout.at("inputs"), {}, "light tile inputs");
-    locations(layout.at("outputs"), {}, "light tile outputs");
-}
 void validate_layout(const Json& layout, std::string_view entry) {
     const bool fragment = entry == "fragmentMain";
     require(layout.at("stage") == (fragment ? "fragment" : "vertex"), "shader stage changed");
     const auto& descriptors = layout.at("descriptors");
-    require(descriptors.is_array() && descriptors.size() == 9, "descriptor count changed");
+    require(descriptors.is_array() && descriptors.size() == 4, "descriptor count changed");
     for (std::size_t i = 0; i < descriptors.size(); ++i) {
         const auto& binding = descriptors[i];
-        const auto set = i < 4 ? 0 : 1;
-        const auto slot = set == 0 ? i : i - 4;
-        require(binding.at("set") == set && binding.at("binding") == slot &&
-                    binding.at("count") == 1,
+        require(binding.at("set") == 0 && binding.at("binding") == i && binding.at("count") == 1,
                 "descriptor set, binding or array count changed");
-        const auto* expected_type = set == 0 ? (slot % 2 ? "sampler" : "sampled_image_2d")
-                                    : slot == 3 ? "sampled_image_2d" : "storage_buffer";
-        require(binding.at("type") == expected_type,
+        require(binding.at("type") == (i % 2 ? "sampler" : "sampled_image_2d"),
                 "descriptor type changed");
-        if (set == 1 && slot != 3)
-            require(binding.at("element_stride") == (slot == 4 ? 4 : slot == 2 ? 112 : 80),
-                    "lighting storage record stride changed");
         require(fragment || !binding.at("used").get<bool>(),
                 "vertex texture bindings are unsupported");
     }
@@ -145,7 +98,7 @@ void validate_gpu_layout(const Json& layout, std::string_view entry) {
     const std::array<int, 3> graphics_strides{224, 4, 208};
     for (std::size_t i = 0; i < expected_count; ++i) {
         const auto& binding = descriptors[i];
-        require(binding.at("set") == (graphics ? 2 : 0) && binding.at("binding") == i &&
+        require(binding.at("set") == (graphics ? 1 : 0) && binding.at("binding") == i &&
                     binding.at("count") == 1,
                 "GPU descriptor set, binding or count changed");
         const int stride = graphics ? graphics_strides[i] : hzb ? 0 : compute_strides[i];
@@ -237,25 +190,22 @@ detail::ShaderCode load(const std::filesystem::path& directory, const char* entr
     require(metadata.at("layout_fingerprint") == fingerprint, "layout fingerprint mismatch");
     if (gpu)
         validate_gpu_layout(layout, entry);
-    else if (std::string_view(entry) == "lightTileMain")
-        validate_tile_layout(layout);
     else
         validate_layout(layout, entry);
     detail::ShaderCode result;
     result.layout_fingerprint = fingerprint;
     result.words.resize(bytes.size() / 4);
     std::memcpy(result.words.data(), bytes.data(), bytes.size());
-    validate_spirv(result.words, std::string_view(entry) == "lightTileMain" ? 5u :
-                   gpu ? ((std::string_view(entry) == "gpuVertexMain" ||
+    validate_spirv(result.words, gpu ? ((std::string_view(entry) == "gpuVertexMain" ||
                                            std::string_view(entry) == "gpuShadowMain") ? 0u : 5u)
                                      : (std::string_view(entry) == "fragmentMain" ? 4u : 0u));
     return result;
 }
 } // namespace
-std::array<detail::ShaderCode, 4>
+std::array<detail::ShaderCode, 3>
 detail::load_shader_bundle(const std::filesystem::path& directory) {
     return {load(directory, "vertexMain"), load(directory, "fragmentMain"),
-            load(directory, "shadowMain"), load(directory, "lightTileMain")};
+            load(directory, "shadowMain")};
 }
 std::array<detail::ShaderCode, 5>
 detail::load_gpu_shader_bundle(const std::filesystem::path& directory) {

src/render/shader_contract.hpp

@@ -10,8 +10,7 @@ struct ShaderCode {
     std::vector<std::uint32_t> words;
     std::string layout_fingerprint;
 };
-// Direct graphics plus the independent 16x16 light-tile compute entry.
-std::array<ShaderCode, 4> load_shader_bundle(const std::filesystem::path& directory);
+std::array<ShaderCode, 3> load_shader_bundle(const std::filesystem::path& directory);
 // Order: opaque vertex, optional instanced shadow vertex, main cull, HZB, post cull.
 std::array<ShaderCode, 5> load_gpu_shader_bundle(const std::filesystem::path& directory);
 } // namespace faset::render::detail

tests/authoring_tests.cpp

@@ -2,7 +2,6 @@
 #include <faset/authoring/templates.hpp>
 #include <faset/authoring/transforms.hpp>
 #include <faset/core/io.hpp>
-#include <cstdint>
 #include <iostream>
 
 #define CHECK(x)                                                                                   \
@@ -26,32 +25,6 @@ int main() {
     const auto root = std::filesystem::temp_directory_path() / ("faset-authoring-" + new_id());
     try {
         auto schemas = builtin_schemas();
-        const auto light = schemas.schema("faset.light");
-        CHECK(light["version"] == 1);
-        const auto defaults = schemas.default_fields("faset.light");
-        CHECK(defaults["kind"] == "directional");
-        CHECK(defaults["enabled"] == true);
-        CHECK(defaults["range"] == 10.0);
-        CHECK(defaults["inner_angle"] < defaults["outer_angle"]);
-        CHECK(defaults["casts_shadow"] == true);
-        CHECK(defaults["shadow_priority"] == 0);
-        auto light_component = Json{{"type", "faset.light"}, {"version", 1}, {"fields", defaults}};
-        schemas.validate_component(light_component);
-        light_component["fields"]["kind"] = "area";
-        fails([&] { schemas.validate_component(light_component); }, "validation.enum");
-        light_component["fields"]["kind"] = "point";
-        light_component["fields"]["range"] = 0;
-        fails([&] { schemas.validate_component(light_component); }, "validation.minimum");
-        light_component["fields"]["range"] = 10;
-        light_component["fields"]["intensity"] = -1;
-        fails([&] { schemas.validate_component(light_component); }, "validation.minimum");
-        light_component["fields"] = {{"kind", "spot"}, {"inner_angle", 0.9}};
-        fails([&] { schemas.validate_component(light_component); }, "validation.light_cone");
-        light_component["fields"] = {{"kind", "spot"},
-                                      {"inner_angle", 0.2},
-                                      {"outer_angle", 0.5},
-                                      {"shadow_priority", std::int64_t{2147483648}}};
-        fails([&] { schemas.validate_component(light_component); }, "validation.maximum");
         AuthoringService service(root, schemas);
         auto created = service.create("Courtyard", 3);
         const std::string id = created["id"];

tests/build_cache_tests.cpp

@@ -0,0 +1,196 @@
+#include <faset/core/io.hpp>
+#include <faset/editor/build_cache.hpp>
+#include <faset/editor/build_service.hpp>
+#include <faset/scripting/project.hpp>
+#include <iostream>
+
+using namespace faset;
+namespace fs = std::filesystem;
+
+namespace {
+void check(bool condition, std::string_view message) {
+    if (!condition)
+        throw std::runtime_error(std::string(message));
+}
+void run(const fs::path& root) {
+    const auto project = root / "project";
+    const auto scripts = project / "Scripts";
+    atomic_write(scripts / "Gameplay.cpp", "#include \"Gameplay.hpp\"\n");
+    atomic_write(scripts / "Gameplay.hpp", "#pragma once\n");
+    atomic_write(scripts / "Extensions/Extra.hpp", "#define SPEED 1\n");
+    const auto compiler = root / "fake-compiler";
+    const auto cmake = root / "fake-cmake";
+    const auto slang = root / "fake-slangc";
+    atomic_write(compiler, "compiler-v1\n");
+    atomic_write(cmake, "cmake-v1\n");
+    atomic_write(slang, "slang-v1\n");
+    editor::BuildConfig config;
+    config.project_root = project;
+    config.engine_root = path_from_utf8(FASET_ENGINE_SOURCE);
+    config.build_directory = project / ".faset/build";
+    config.cmake = path_to_utf8(cmake);
+    config.configure_arguments = {
+        "-DCMAKE_C_COMPILER=" + path_to_utf8(compiler),
+        "-DCMAKE_CXX_COMPILER=" + path_to_utf8(compiler),
+        "-DSLANGC_EXECUTABLE=" + path_to_utf8(slang)};
+
+    const scripting::LuaProject none;
+    const auto initial = editor::capture_build_inputs(config, none);
+    atomic_write(scripts / "Extensions/Extra.hpp", "#define SPEED 2\n");
+    const auto changed_header = editor::capture_build_inputs(config, none);
+    check(initial.source_hash != changed_header.source_hash &&
+              initial.fingerprint() != changed_header.fingerprint(),
+          "Nested gameplay header changes the complete source snapshot");
+
+    atomic_write(scripts / "main.lua", "return {}\n");
+    atomic_write_json(project / "project.faset.json",
+                      {{"format", "faset.project"},
+                       {"version", 1},
+                       {"scripting", {{"lua", {{"scripts", {"Scripts/main.lua"}}}}}}});
+    auto lua = scripting::loadLuaProject(project);
+    const auto with_lua = editor::capture_build_inputs(config, lua);
+    atomic_write(scripts / "other.lua", "return {}\n");
+    auto manifest = read_json(project / "project.faset.json");
+    manifest["scripting"]["lua"]["scripts"].push_back("Scripts/other.lua");
+    atomic_write_json(project / "project.faset.json", manifest);
+    lua = scripting::loadLuaProject(project);
+    const auto changed_declaration = editor::capture_build_inputs(config, lua);
+    check(with_lua.source_hash != changed_declaration.source_hash,
+          "Lua entry declaration changes the source snapshot");
+
+    const auto native = config.build_directory / "Debug";
+    editor::ensure_native_toolchain_stamp(config, native, changed_declaration);
+    atomic_write(native / "sentinel", "keep\n");
+    editor::ensure_native_toolchain_stamp(config, native, changed_declaration);
+    check(fs::exists(native / "sentinel"), "Unchanged toolchain preserves the native tree");
+    atomic_write(compiler, "compiler-v2\n");
+    const auto changed_tool = editor::capture_build_inputs(config, lua);
+    check(changed_tool.source_hash == changed_declaration.source_hash &&
+              changed_tool.toolchain_hash != changed_declaration.toolchain_hash,
+          "Changing compiler bytes at the same path changes toolchain identity");
+    editor::ensure_native_toolchain_stamp(config, native, changed_tool);
+    check(!fs::exists(native / "sentinel"),
+          "Changed toolchain invalidates only the generated native tree");
+
+    const auto user_directory = root / "important-user-data";
+    atomic_write(user_directory / "do-not-delete.txt", "valuable\n");
+    bool refused_unowned{};
+    try {
+        editor::ensure_native_toolchain_stamp(config, user_directory, changed_tool);
+    } catch (const std::exception&) {
+        refused_unowned = true;
+    }
+    check(refused_unowned && fs::is_regular_file(user_directory / "do-not-delete.txt"),
+          "Unowned native directory is never cleared");
+    std::error_code native_link_error;
+    fs::create_directory_symlink(user_directory, config.build_directory / "Release",
+                                 native_link_error);
+    if (!native_link_error) {
+        bool refused_link{};
+        try {
+            editor::ensure_native_toolchain_stamp(config, config.build_directory / "Release",
+                                                  changed_tool);
+        } catch (const std::exception&) {
+            refused_link = true;
+        }
+        check(refused_link && fs::is_regular_file(user_directory / "do-not-delete.txt"),
+              "Symlinked native directory cannot redirect cleanup into user data");
+    }
+
+    const auto relative_tool = project / "tools/cmake-fixture";
+    atomic_write(relative_tool, "relative-cmake-v1\n");
+    auto relative_config = config;
+    relative_config.cmake = "tools/cmake-fixture";
+    const auto relative_before = editor::capture_build_inputs(relative_config, lua);
+    atomic_write(relative_tool, "relative-cmake-v2\n");
+    check(relative_before.toolchain_hash !=
+              editor::capture_build_inputs(relative_config, lua).toolchain_hash,
+          "Relative CMake executable resolves from the project working directory");
+    auto typed_config = config;
+    const auto typed_compiler = root / "typed-compiler";
+    atomic_write(typed_compiler, "typed-v1\n");
+    typed_config.configure_arguments = {
+        "-DCMAKE_C_COMPILER:FILEPATH=" + path_to_utf8(typed_compiler)};
+    const auto typed_before = editor::capture_build_inputs(typed_config, lua);
+    atomic_write(typed_compiler, "typed-v2\n");
+    check(typed_before.toolchain_hash !=
+              editor::capture_build_inputs(typed_config, lua).toolchain_hash,
+          "Typed CMake compiler overrides are included in toolchain identity");
+    auto malicious_config = config;
+    malicious_config.configure_arguments.push_back(
+        "-DFASET_GAMEPLAY_SOURCE_DIR:PATH=" + path_to_utf8(root / "outside"));
+    bool refused_source_override{};
+    try {
+        (void)editor::capture_build_inputs(malicious_config, lua);
+    } catch (const std::exception&) {
+        refused_source_override = true;
+    }
+    check(refused_source_override,
+          "Configure arguments cannot redirect gameplay compilation away from hashed Scripts");
+
+    const auto staged = editor::stage_gameplay_sources(config, changed_tool, lua,
+                                                        "snapshot-fixture");
+    check(staged != scripts && fs::is_regular_file(staged / "Gameplay.cpp") &&
+              read_text(staged / "Extensions/Extra.hpp") == "#define SPEED 2\n",
+          "Native gameplay compilation uses a complete staged Scripts snapshot");
+    atomic_write(scripts / "Extensions/Extra.hpp", "#define SPEED 999\n");
+    check(read_text(staged / "Extensions/Extra.hpp") == "#define SPEED 2\n",
+          "A live edit cannot alter the source bytes of an in-flight native build");
+    atomic_write(scripts / "Extensions/Extra.hpp", "#define SPEED 2\n");
+    check(editor::stage_gameplay_sources(config, changed_tool, lua, "snapshot-again") ==
+              staged,
+          "Identical sources retain a stable native path for incremental Ninja builds");
+
+    atomic_write(native / "faset_player", "player-v1\n");
+    atomic_write(native / "faset_schema_exporter", "exporter-v1\n");
+    atomic_write(native / "CMakeCache.txt", "recipe-v1\n");
+    atomic_write(native / "shaders/vertexMain.spv", "shader-v1\n");
+    atomic_write(native / "faset_runtime.dll", "runtime-v1\n");
+    auto package_key = [&] (const editor::BuildInputs& inputs) {
+        return editor::build_package_key(inputs, native, "Debug", native / "faset_player",
+                                         native / "faset_schema_exporter");
+    };
+    const auto first_key = package_key(changed_tool);
+    check(first_key != package_key(changed_declaration) &&
+              first_key != package_key(with_lua),
+          "Toolchain and Lua source changes invalidate package identity");
+    auto option_config = config;
+    option_config.configure_arguments.push_back("-DFASET_TEST_OPTION=ON");
+    check(first_key != package_key(editor::capture_build_inputs(option_config, lua)),
+          "Configure option changes invalidate package identity");
+    atomic_write(native / "shaders/vertexMain.spv", "shader-v2\n");
+    check(first_key != package_key(changed_tool),
+          "Shader bytes invalidate package identity");
+    atomic_write(native / "shaders/vertexMain.spv", "shader-v1\n");
+    atomic_write(native / "faset_runtime.dll", "runtime-v2\n");
+    check(first_key != package_key(changed_tool),
+          "Runtime DLL bytes invalidate package identity");
+
+    fs::create_directories(root / "outside");
+    std::error_code link_error;
+    fs::create_directory_symlink(root / "outside", scripts / "linked", link_error);
+    if (!link_error) {
+        bool rejected = false;
+        try {
+            (void)editor::capture_build_inputs(config, lua);
+        } catch (const std::exception&) {
+            rejected = true;
+        }
+        check(rejected, "Source snapshot refuses a symlink escaping Scripts");
+    }
+}
+} // namespace
+
+int main() {
+    const auto root = fs::temp_directory_path() / path_from_utf8("Faset build cache Café 世界 " + new_id());
+    try {
+        run(root);
+        fs::remove_all(root);
+        std::cout << "Source, toolchain and native package identity contracts passed\n";
+        return 0;
+    } catch (const std::exception& error) {
+        std::cerr << error.what() << '\n';
+        fs::remove_all(root);
+        return 1;
+    }
+}

tests/build_diagnostics_tests.cpp

@@ -0,0 +1,76 @@
+#include <faset/editor/build_diagnostics.hpp>
+#include <faset/core/io.hpp>
+#include <iostream>
+#include <stdexcept>
+
+using namespace faset;
+namespace fs = std::filesystem;
+
+namespace {
+void check(bool condition, std::string_view message) {
+    if (!condition)
+        throw std::runtime_error(std::string(message));
+}
+void contracts() {
+    const auto project = fs::path("/project");
+    auto rows = editor::parse_build_diagnostics(
+        "/project/Scripts/Game.cpp:17:4: error: bad field\n", "compile", project);
+    check(rows.size() == 1 && rows[0].at("file") == "Scripts/Game.cpp" &&
+              rows[0].at("line") == 17 && rows[0].at("column") == 4 &&
+              rows[0].at("severity") == "error" && rows[0].at("phase") == "compile",
+          "Clang error has a project-relative source location");
+    rows = editor::parse_build_diagnostics(
+        "\x1b[31mScripts/player.lua:6: unexpected symbol near '='\x1b[0m\n",
+        "schema", project);
+    check(rows.size() == 1 && rows[0].at("file") == "Scripts/player.lua" &&
+              rows[0].at("line") == 6 && rows[0].at("severity") == "error" &&
+              rows[0].at("message") == "unexpected symbol near '='",
+          "Lua syntax error and ANSI stripping work");
+    const auto windows = path_from_utf8(R"(C:\Café)");
+    rows = editor::parse_build_diagnostics(
+        R"(C:\Café\Scripts\Game.cpp(17,4): error C2143: syntax error)" "\n"
+        R"(C:\Café\Scripts\Game.cpp:19:2: warning: suspicious conversion)" "\n",
+        "compile", windows);
+    check(rows.size() == 2 && rows[0].at("file") == "Scripts/Game.cpp" &&
+              rows[0].at("code") == "C2143" && rows[0].at("line") == 17 &&
+              rows[1].at("severity") == "warning" && rows[1].at("line") == 19,
+          "Windows drive colon and Unicode directory remain intact");
+    rows = editor::parse_build_diagnostics(
+        "Scripts/Game.cpp:9:3: error: missing value\n"
+        "    broken call\n"
+        "    ^~~~~~\n"
+        "Scripts/Game.cpp:4:1: note: declared here\n",
+        "compile", project);
+    check(rows.size() == 2 && rows[0].at("severity") == "error" &&
+              rows[1].at("severity") == "note" && rows[1].at("file") == "Scripts/Game.cpp",
+          "Caret and source excerpts do not become duplicate diagnostics");
+    rows = editor::parse_build_diagnostics(
+        "/outside/Scripts/Game.cpp:4:2: error: external\n"
+        "../Scripts/Escape.cpp:5:2: error: escaped\n",
+        "compile", project);
+    check(rows.size() == 2 && !rows[0].contains("file") && !rows[1].contains("file"),
+          "External and traversing sources are never navigable");
+    rows = editor::parse_build_diagnostics(
+        "Scripts/../Scripts/Game.cpp:4:2: error: disguised traversal\n"
+        "Scripts/Game.cpp:4:0: error: invalid column\n",
+        "compile", project);
+    check(rows.size() == 1 && !rows[0].contains("file"),
+          "Traversal stays non-navigable and zero columns are rejected");
+    std::string noisy;
+    for (int index = 0; index < 300; ++index)
+        noisy += "Scripts/Game.cpp:2:1: warning: repeated\n";
+    check(editor::parse_build_diagnostics(noisy, "compile", project).size() <= 200,
+          "Structured diagnostic count is bounded");
+}
+} // namespace
+
+int main() {
+    try {
+        contracts();
+        std::cout << "Build diagnostic parsing contracts passed\n";
+        return 0;
+    } catch (const std::exception& error) {
+        std::cerr << error.what() << '\n';
+        return 1;
+    }
+}

tests/build_schema_tests.cpp

@@ -142,13 +142,74 @@ int test_main(int argc, char** argv) {
         config.configure_arguments = {"-DCMAKE_CXX_COMPILER=fixture-does-not-compile"};
         editor::BuildService builds(config);
         builds.scaffold("Schema publication", 2);
+        atomic_write(config.project_root / "Scripts/Extensions/BuildOnly.hpp",
+                     "#define BUILD_ONLY 1\n");
         authoring::AuthoringService authoring(config.project_root, authoring::builtin_schemas());
         const auto valid = manifest();
         atomic_write_json(config.project_root / "schema-fixture.json", valid);
-        const auto first = builds.wait(builds.start_build());
+        {
+            auto compiler_config = config;
+            compiler_config.project_root = root / "c-only-compiler-project";
+            compiler_config.configure_arguments = {
+                "-DCMAKE_C_COMPILER:FILEPATH=fixture-c-only"};
+            editor::BuildService compiler_build(compiler_config);
+            compiler_build.scaffold("Compiler argument fixture", 2);
+            atomic_write_json(compiler_config.project_root / "schema-fixture.json", valid);
+            const auto compiler_result = compiler_build.wait(compiler_build.start_build());
+            check(compiler_result.state == "succeeded",
+                  "C-only compiler override fixture builds: " + compiler_result.error);
+            const auto compiler_args =
+                read_json(compiler_config.project_root / "configure-fixture.json");
+            std::size_t c_overrides{};
+            bool cxx_default{};
+            for (const auto& arg : compiler_args) {
+                const auto text = arg.get<std::string>();
+                if (text.starts_with("-DCMAKE_C_COMPILER")) {
+                    ++c_overrides;
+                    check(text == "-DCMAKE_C_COMPILER:FILEPATH=fixture-c-only",
+                          "Typed C override is not replaced by a default compiler");
+                }
+                if (text.starts_with("-DCMAKE_CXX_COMPILER="))
+                    cxx_default = true;
+            }
+            check(c_overrides == 1 && cxx_default,
+                  "C and C++ compiler defaults are selected independently");
+        }
+        auto first = builds.wait(builds.start_build());
         check(first.state == "succeeded", "Valid custom schema v2 publishes: " + first.error);
+        fs::path compiled_scripts;
+        for (const auto& arg : read_json(config.project_root / "configure-fixture.json")) {
+            const auto text = arg.get<std::string>();
+            constexpr std::string_view prefix = "-DFASET_GAMEPLAY_SOURCE_DIR=";
+            if (text.starts_with(prefix))
+                compiled_scripts = path_from_utf8(text.substr(prefix.size()));
+        }
+        check(!compiled_scripts.empty() &&
+                  compiled_scripts != config.project_root / "Scripts" &&
+                  read_text(compiled_scripts / "Extensions/BuildOnly.hpp") ==
+                      "#define BUILD_ONLY 1\n",
+              "Native C++ build receives the immutable source snapshot");
+        const auto repeated = builds.wait(builds.start_build());
+        check(repeated.state == "succeeded" &&
+                  repeated.result.at("generation") == first.result.at("generation") &&
+                  repeated.result.at("schema_cache_hit") == true &&
+                  repeated.result.at("generation_reused") == true &&
+                  read_text(config.project_root / "schema-export-count.txt") == "1",
+              "Unchanged native build reuses a verified schema generation");
+        atomic_write(path_from_utf8(first.result.at("schema").get<std::string>()), "truncated");
+        first = builds.wait(builds.start_build());
+        check(first.state == "succeeded" && first.result.at("schema_cache_hit") == false &&
+                  read_text(config.project_root / "schema-export-count.txt") == "2",
+              "Corrupt schema cannot be a cache hit");
+        atomic_write(path_from_utf8(first.result.at("directory").get<std::string>()) /
+                         "shaders/vertexMain.spv",
+                     "corrupt");
+        first = builds.wait(builds.start_build());
+        check(first.state == "succeeded" && first.result.at("schema_cache_hit") == false &&
+                  read_text(config.project_root / "schema-export-count.txt") == "3",
+              "Corrupt shader cannot be a cache hit");
         const auto directory = path_from_utf8(first.result.at("directory").get<std::string>());
-        for (const auto* entry : {"lightTileMain", "gpuVertexMain", "gpuShadowMain", "gpuCullMain",
+        for (const auto* entry : {"gpuVertexMain", "gpuShadowMain", "gpuCullMain",
                                   "gpuHzbMain", "gpuPostCullMain"})
             for (const auto* extension : {".spv", ".reflection.json"})
                 check(fs::is_regular_file(directory / "shaders" /
@@ -161,6 +222,34 @@ int test_main(int argc, char** argv) {
         const auto previous_player = sha256_file(player);
         const auto previous_schema = read_text(schema);
         const auto previous_manifest = read_text(directory / "manifest.json");
+        atomic_write(config.project_root / "emit-clang-error-and-fail-build", "fixture\n");
+        const auto compile_failed = builds.wait(builds.start_build());
+        check(compile_failed.state == "failed" &&
+                  read_text(last_build) == previous_pointer &&
+                  compile_failed.json().at("diagnostics").size() == 1 &&
+                  compile_failed.json().at("diagnostics")[0].at("file") ==
+                      "Scripts/Gameplay.cpp" &&
+                  compile_failed.log.find("fixture compile failure") != std::string::npos,
+              "Failed compiler output retains raw log and structured source location");
+        fs::remove(config.project_root / "emit-clang-error-and-fail-build");
+        atomic_write(config.project_root / "fail-unparseable-build", "fixture\n");
+        const auto generic_failed = builds.wait(builds.start_build());
+        check(generic_failed.state == "failed" &&
+                  generic_failed.json().at("diagnostics").size() == 1 &&
+                  generic_failed.json().at("diagnostics")[0].at("severity") == "error" &&
+                  !generic_failed.json().at("diagnostics")[0].contains("file") &&
+                  read_text(last_build) == previous_pointer,
+              "Unparseable process failure has a non-navigable diagnostic");
+        fs::remove(config.project_root / "fail-unparseable-build");
+        atomic_write(config.project_root / "Scripts/Extensions/BuildOnly.hpp",
+                     "#define BUILD_ONLY 3\n");
+        atomic_write(config.project_root / "mutate-cpp-header-during-build", "fixture\n");
+        const auto raced_header = builds.wait(builds.start_build());
+        check(raced_header.state == "failed" && read_text(last_build) == previous_pointer,
+              "Header changed during schema export cannot publish a mixed build");
+        fs::remove(config.project_root / "mutate-cpp-header-during-build");
+        atomic_write(config.project_root / "Scripts/Extensions/BuildOnly.hpp",
+                     "#define BUILD_ONLY 1\n");
         check(!first.result.at("lua_enabled").get<bool>() &&
                   !fs::exists(directory / "project.faset.json"),
               "C++-only build publishes no Lua sources or project manifest");
@@ -169,6 +258,11 @@ int test_main(int argc, char** argv) {
               "C++-only build explicitly disables the Lua VM in CMake");
         authoring.replace_external_schemas(read_json(schema));
         const auto previous_registry = authoring.schemas().manifest();
+        std::size_t published_generations{};
+        for (const auto& entry : fs::directory_iterator(directory.parent_path())) {
+            (void)entry;
+            ++published_generations;
+        }
         check(authoring.schemas().schema("game.mover").at("version") == 2,
               "Matching custom v2 metadata reaches authoring");
         migration_contracts(config.project_root / "migration-contracts", read_json(schema));
@@ -252,9 +346,11 @@ int test_main(int argc, char** argv) {
             std::size_t generations{};
             for (const auto& entry : fs::directory_iterator(directory.parent_path())) {
                 ++generations;
-                check(entry.path() == directory, "Invalid build leaves no staging or generation");
+                check(!entry.path().filename().string().starts_with(".staging-"),
+                      "Invalid build leaves no staging generation");
             }
-            check(generations == 1, "Only the validated build generation remains");
+            check(generations == published_generations,
+                  "Invalid build publishes no new generation");
             bool rejected{};
             try {
                 authoring.replace_external_schemas(invalid[index]);
@@ -305,6 +401,8 @@ int test_main(int argc, char** argv) {
               "Later edits never mutate an already published Lua generation");
         const auto lua_pointer = read_text(last_build);
         for (const auto* marker : {"mutate-lua-during-build", "mutate-lua-snapshot"}) {
+            atomic_write(config.project_root / "Scripts/main.lua",
+                         std::string(lua_source) + "-- force a schema export\n");
             atomic_write(config.project_root / marker, "fixture\n");
             const auto raced = builds.wait(builds.start_build());
             check(raced.state == "failed" && read_text(last_build) == lua_pointer,

tests/build_schema_tool.cpp

@@ -8,6 +8,9 @@ using namespace faset;
 int tool_main(int argc, char** argv) {
     try {
         if (argc >= 3 && std::string_view(argv[1]) == "--output") {
+            const auto count_file = fs::path("schema-export-count.txt");
+            const auto count = fs::exists(count_file) ? std::stoi(read_text(count_file)) : 0;
+            atomic_write(count_file, std::to_string(count + 1));
             if (argc == 5 && std::string_view(argv[3]) == "--project") {
                 const auto snapshot = path_from_utf8(argv[4]);
                 const auto project = read_json(snapshot / "project.faset.json");
@@ -21,6 +24,8 @@ int tool_main(int argc, char** argv) {
                 if (fs::exists("mutate-lua-snapshot"))
                     atomic_write(snapshot / "Scripts/main.lua", "-- corrupt snapshot\n");
             }
+            if (fs::exists("mutate-cpp-header-during-build"))
+                atomic_write("Scripts/Extensions/BuildOnly.hpp", "#define BUILD_ONLY 2\n");
             atomic_write_json(path_from_utf8(argv[2]), read_json("schema-fixture.json"));
             return 0;
         }
@@ -34,8 +39,18 @@ int tool_main(int argc, char** argv) {
             std::cout << "Native packaging fixture validated\n";
             return 0;
         }
-        if (argc > 2 && std::string_view(argv[1]) == "--build")
+        if (argc > 2 && std::string_view(argv[1]) == "--build") {
+            if (fs::exists("emit-clang-error-and-fail-build")) {
+                std::cerr << path_to_utf8(fs::current_path() / "Scripts/Gameplay.cpp")
+                          << ":7:3: error: fixture compile failure\n";
+                return 1;
+            }
+            if (fs::exists("fail-unparseable-build")) {
+                std::cerr << "Synthetic native build failed without a source location\n";
+                return 1;
+            }
             return 0;
+        }
         fs::path build;
         for (int i = 1; i + 1 < argc; ++i)
             if (std::string_view(argv[i]) == "-B")
@@ -60,7 +75,7 @@ int tool_main(int argc, char** argv) {
         for (const auto* target : {"faset_player", "faset_schema_exporter"})
             fs::copy_file(self, build / (std::string(target) + suffix),
                           fs::copy_options::overwrite_existing);
-        for (const auto* entry : {"vertexMain", "fragmentMain", "shadowMain", "lightTileMain",
+        for (const auto* entry : {"vertexMain", "fragmentMain", "shadowMain",
                                   "gpuVertexMain", "gpuShadowMain", "gpuCullMain",
                                   "gpuHzbMain", "gpuPostCullMain"})
             for (const auto* extension : {".spv", ".reflection.json"})

tests/build_service_tests.cpp

@@ -1,8 +1,12 @@
 #include "assets_image_fixtures.hpp"
+#include <algorithm>
+#include <atomic>
 #include <bit>
 #include <chrono>
 #include <cstdlib>
+#include <functional>
 #include <faset/assets/asset_pipeline.hpp>
+#include <faset/authoring/service.hpp>
 #include <faset/core/hash.hpp>
 #include <faset/core/io.hpp>
 #include <faset/core/process.hpp>
@@ -42,6 +46,102 @@ Json scene(int dimension) {
             {"name", "Build test"},      {"dimension", dimension}, {"entities", Json::array()},
             {"instances", Json::array()}};
 }
+void starter_contracts(const fs::path& root) {
+    for (const int dimension : {2, 3}) {
+        for (const char* language : {"cpp", "lua"}) {
+            const auto project = root / path_from_utf8(std::string("Starter café ") + language +
+                                                        std::to_string(dimension));
+            editor::BuildConfig config;
+            config.project_root = project;
+            config.engine_root = path_from_utf8(FASET_ENGINE_SOURCE);
+            editor::BuildService service(config);
+            service.scaffold("Starter", dimension, language);
+            const auto manifest = read_json(project / "project.faset.json");
+            const auto start = read_json(project / "Scenes/main.scene.json");
+            require(manifest.at("dimension") == dimension &&
+                        manifest.at("start_scene") == "Scenes/main.scene.json",
+                    "Explicit starter has the requested scene type and startup path");
+            require(start.at("dimension") == dimension && !start.at("entities").empty(),
+                    "Starter scene is valid and has visible contents");
+            auto builtins = start;
+            bool has_behavior = false;
+            for (auto& entity : builtins["entities"]) {
+                auto& components = entity["components"].get_ref<Json::array_t&>();
+                std::erase_if(components, [&](const Json& component) {
+                    const auto custom =
+                        !component.at("type").get<std::string>().starts_with("faset.");
+                    has_behavior |= custom;
+                    return custom;
+                });
+            }
+            require(has_behavior, "Starter scene binds its gameplay behavior");
+            authoring::validate_scene(builtins, authoring::builtin_schemas());
+            if (std::string_view(language) == "lua") {
+                require(!fs::exists(project / "Scripts/Gameplay.cpp") &&
+                            !fs::exists(project / "Scripts/Gameplay.hpp"),
+                        "Lua starter has no C++ gameplay stub");
+                require(manifest.at("scripting").at("lua").at("scripts") ==
+                            Json::array({"Scripts/main.lua"}) &&
+                            scripting::loadLuaProject(project).enabled() &&
+                            fs::is_regular_file(project / ".luarc.json") &&
+                            fs::is_regular_file(project / "Scripts/.luarc.json") &&
+                            fs::is_regular_file(project / ".faset/lua/faset.lua"),
+                        "Lua starter declares an actual runnable module");
+            } else {
+                require(fs::is_regular_file(project / "Scripts/Gameplay.cpp") &&
+                            fs::is_regular_file(project / "Scripts/Gameplay.hpp") &&
+                            !manifest.contains("scripting"),
+                        "C++ starter contains its compiled gameplay module");
+            }
+            const auto marker = read_text(project / "Scenes/main.scene.json");
+            bool rejected = false;
+            try {
+                service.scaffold("Again", dimension, language);
+            } catch (const std::exception&) {
+                rejected = true;
+            }
+            require(rejected && read_text(project / "Scenes/main.scene.json") == marker,
+                    "Explicit creation rejects existing project without overwriting it");
+        }
+    }
+    editor::BuildConfig legacy;
+    legacy.project_root = root / "legacy";
+    legacy.engine_root = path_from_utf8(FASET_ENGINE_SOURCE);
+    editor::BuildService(legacy).scaffold("Legacy", 3);
+    require(!fs::exists(legacy.project_root / "Scenes/main.scene.json"),
+            "Two-argument scaffold retains its prior no-scene behavior");
+    const auto concurrent_root = root / "concurrent";
+    editor::BuildConfig concurrent;
+    concurrent.project_root = concurrent_root;
+    concurrent.engine_root = path_from_utf8(FASET_ENGINE_SOURCE);
+    editor::BuildService first(concurrent), second(concurrent);
+    std::atomic<int> ready = 0;
+    std::atomic<int> successes = 0;
+    auto attempt = [&](editor::BuildService& service, const char* name) {
+        ++ready;
+        while (ready.load() < 2)
+            std::this_thread::yield();
+        try {
+            service.scaffold(name, 2, "lua");
+            ++successes;
+        } catch (const std::exception&) {
+        }
+    };
+    std::thread a(attempt, std::ref(first), "First");
+    std::thread b(attempt, std::ref(second), "Second");
+    a.join();
+    b.join();
+    require(successes == 1, "Two concurrent creators publish exactly one starter");
+    const auto winner = read_json(concurrent_root / "project.faset.json");
+    require(winner.at("name") == "First" || winner.at("name") == "Second",
+            "Published manifest belongs to the successful creator");
+    require(fs::is_regular_file(concurrent_root / "Scripts/main.lua") &&
+                fs::is_regular_file(concurrent_root / "Scenes/main.scene.json"),
+            "The winning starter publishes all required files");
+    const auto ignore = read_text(concurrent_root / ".gitignore");
+    require(ignore.find("!.faset/lua/faset.lua") != std::string::npos,
+            "LuaLS declarations are commit-friendly in generated projects");
+}
 void lua_project_contracts(const fs::path& root) {
     fs::create_directories(root);
     require(!scripting::loadLuaProject(root).enabled(), "No manifest means no Lua dependency");
@@ -379,6 +479,7 @@ int test_main(int argc, char** argv) {
     try {
         fs::create_directories(temporary);
         lua_project_contracts(temporary / "lua-project");
+        starter_contracts(temporary / "starters");
         const auto original_executable = fs::absolute(path_from_utf8(argv[0]));
         const auto executable = temporary / original_executable.filename();
         fs::copy_file(original_executable, executable);

tests/editor_autosave_tests.cpp

@@ -0,0 +1,119 @@
+#include <faset/authoring/service.hpp>
+#include <faset/core/io.hpp>
+#include <faset/editor/autosave.hpp>
+#include <chrono>
+#include <iostream>
+
+using namespace faset;
+using namespace std::chrono_literals;
+namespace fs = std::filesystem;
+
+namespace {
+void check(bool value, std::string_view message) {
+    if (!value)
+        throw std::runtime_error(std::string(message));
+}
+void contracts(const fs::path& root) {
+    authoring::AuthoringService service(root);
+    const auto created = service.create("Before", 2);
+    const auto id = created.at("id").get<std::string>();
+    const auto path = root / "Scenes/main.scene.json";
+    service.save(id, "Scenes/main.scene.json");
+    int saves{};
+    editor::AutosaveController autosave([&](const std::string& document, std::uint64_t revision) {
+        ++saves;
+        return service.save(document, {}, revision);
+    });
+    using Clock = editor::AutosaveController::Clock;
+    const auto start = Clock::time_point{};
+    autosave.observe(service.documents(), start, true);
+    for (int index = 1; index <= 3; ++index) {
+        const auto revision = service.query(id).at("revision").get<std::uint64_t>();
+        service.transact(id, revision,
+                         Json::array({{{"op", "scene.rename"},
+                                      {"name", "Edit " + std::to_string(index)}}}));
+        autosave.observe(service.documents(), start + index * 100ms, true);
+    }
+    const auto play_snapshot = service.query(id).at("scene");
+    autosave.observe(service.documents(), start + 2299ms, true);
+    check(saves == 0 && read_json(path).at("name") == "Before",
+          "Rapid edits coalesce until the last revision is idle for two seconds");
+    autosave.observe(service.documents(), start + 2301ms, true);
+    check(saves == 1 && read_json(path).at("name") == "Edit 3" &&
+              service.query(id).at("scene") == play_snapshot &&
+              autosave.status().at("documents")[0].at("state") == "saved",
+          "Named scene saves once without changing the Play snapshot");
+    const auto current_revision = service.query(id).at("revision").get<std::uint64_t>();
+    check(service.undo(id, current_revision).at("scene").at("name") == "Edit 2",
+          "Undo remains available after autosave");
+    bool stale_rejected{};
+    try {
+        service.save(id, {}, current_revision);
+    } catch (const Error& error) {
+        stale_rejected = error.code() == "revision.conflict";
+    }
+    check(stale_rejected, "A stale autosave revision cannot save a newer document");
+
+    const auto external = read_text(path) + " \n";
+    atomic_write(path, external);
+    const auto revision = service.query(id).at("revision").get<std::uint64_t>();
+    service.transact(id, revision,
+                     Json::array({{{"op", "scene.rename"}, {"name", "After external edit"}}}));
+    autosave.observe(service.documents(), start + 3000ms, true);
+    autosave.observe(service.documents(), start + 5100ms, true);
+    check(saves == 2 && read_text(path) == external &&
+              autosave.status().at("documents")[0].at("state") == "conflict",
+          "Disk conflict does not overwrite external changes");
+    autosave.observe(service.documents(), start + 10000ms, true);
+    check(saves == 2, "A failed autosave does not retry every polling frame");
+
+    const auto unnamed = service.create("Unnamed", 2);
+    autosave.observe(service.documents(), start + 10100ms, true);
+    bool found_unnamed{};
+    const auto unnamed_status = autosave.status();
+    for (const auto& row : unnamed_status.at("documents"))
+        if (row.at("id") == unnamed.at("id"))
+            found_unnamed = row.at("state") == "save_as_required";
+    check(found_unnamed &&
+              fs::is_regular_file(root / ".faset/recovery" /
+                                  (unnamed.at("id").get<std::string>() + ".json")),
+          "Unnamed scene remains recoverable without receiving an implicit save path");
+    autosave.observe(service.documents(), start + 10200ms, false);
+    check(!autosave.status().at("enabled").get<bool>() && saves == 2,
+          "Disabled autosave leaves recovery journaling active");
+
+    int failed_attempts{};
+    editor::AutosaveController failing([&](const std::string&, std::uint64_t) -> Json {
+        ++failed_attempts;
+        throw Error("io.write", "Synthetic read-only destination");
+    });
+    Json fake_documents = Json::array(
+        {{{"id", "failure-fixture"}, {"revision", 1},
+          {"path", "Scenes/fixture.scene.json"}, {"dirty", true}}});
+    failing.observe(fake_documents, start, true);
+    failing.observe(fake_documents, start + 2100ms, true);
+    check(failed_attempts == 1 &&
+              failing.status().at("documents")[0].at("state") == "failed",
+          "Write failures remain visible");
+    failing.observe(fake_documents, start + 10000ms, true);
+    check(failed_attempts == 1, "A failed write does not retry on every frame");
+    fake_documents[0]["revision"] = 2;
+    failing.observe(fake_documents, start + 10100ms, true);
+    failing.observe(fake_documents, start + 12200ms, true);
+    check(failed_attempts == 2, "A newer revision receives a fresh autosave deadline");
+}
+} // namespace
+
+int main() {
+    const auto root = fs::temp_directory_path() / ("faset-autosave-" + new_id());
+    try {
+        contracts(root);
+        fs::remove_all(root);
+        std::cout << "Revision-aware autosave contracts passed\n";
+        return 0;
+    } catch (const std::exception& error) {
+        std::cerr << error.what() << '\n';
+        fs::remove_all(root);
+        return 1;
+    }
+}

tests/editor_session_tests.cpp

@@ -1,9 +1,18 @@
 #include <faset/core/io.hpp>
 #include <faset/editor/session.hpp>
+#include <chrono>
 #include <iostream>
+#include <thread>
 
-int main() {
+int test_main(int argc, char** argv) {
     using namespace faset;
+    if (argc >= 3 && std::string_view(argv[1]) == "--editor-probe") {
+        Json arguments = Json::array();
+        for (int index = 3; index < argc; ++index)
+            arguments.push_back(argv[index]);
+        atomic_write_json(path_from_utf8(argv[2]), arguments);
+        return 0;
+    }
     const auto root = std::filesystem::temp_directory_path() /
                       path_from_utf8("Faset Café 世界 session " + new_id());
     try {
@@ -27,6 +36,8 @@ int main() {
         require(!session.play_pending() && !session.playing(), "test",
                 "Stop must cancel a pending Play build");
         const auto initial = commands.call("faset_project_settings_get", Json::object());
+        require(initial.at("settings").at("editor").at("autosave") == true, "test",
+                "Missing autosave setting must read as enabled");
         auto changed = commands.call("faset_project_settings_set",
                                      {{"revision", initial.at("revision")},
                                       {"settings",
@@ -66,15 +77,57 @@ int main() {
         atomic_write_json(root / "project.faset.json", external);
         rejects({{"revision", changed.at("revision")}, {"settings", {{"name", "Race"}}}},
                 "revision.conflict");
-        const auto reloaded = commands.call("faset_project_settings_get", Json::object());
+        auto reloaded = commands.call("faset_project_settings_get", Json::object());
+        auto explicit_default = external;
+        explicit_default["editor"]["autosave"] = true;
+        atomic_write_json(root / "project.faset.json", explicit_default);
+        rejects({{"revision", reloaded.at("revision")},
+                 {"settings", {{"name", "Lost external write"}}}},
+                "revision.conflict");
+        reloaded = commands.call("faset_project_settings_get", Json::object());
         changed =
             commands.call("faset_project_settings_set", {{"revision", reloaded.at("revision")},
                                                          {"settings", {{"name", "Preserved"}}}});
         require(changed.at("settings").at("custom_tool").at("keep") == true, "test",
                 "Saving settings erased unknown project metadata");
         require(changed.at("settings").at("scripting") == external.at("scripting") &&
-                    changed.at("settings").at("editor") == external.at("editor"),
+                    changed.at("settings").at("editor").at("script_editor") ==
+                        external.at("editor").at("script_editor"),
                 "test", "Project settings erased Lua configuration or external editor command");
+        const auto autosave_off = commands.call(
+            "faset_project_settings_set",
+            {{"revision", changed.at("revision")},
+             {"settings", {{"editor", {{"autosave", false}}}}}});
+        require(autosave_off.at("settings").at("editor").at("autosave") == false &&
+                    session.project().at("editor").at("script_editor") ==
+                        external.at("editor").at("script_editor"),
+                "test", "Autosave setting must merge without erasing the editor command");
+        session.poll();
+        require(commands.call("faset_autosave_status", Json::object()).at("enabled") == false,
+                "test", "Autosave disable must take effect in the current session");
+        {
+            editor::Session reopened({root, path_from_utf8(FASET_TEST_ENGINE), {}});
+            reopened.poll();
+            require(reopened.commands()
+                            .call("faset_autosave_status", Json::object())
+                            .at("enabled") == false,
+                    "test", "Autosave setting must survive Editor reopen");
+        }
+        rejects({{"revision", changed.at("revision")},
+                 {"settings", {{"editor", {{"autosave", true}}}}}},
+                "revision.conflict");
+        rejects({{"revision", autosave_off.at("revision")},
+                 {"settings", {{"editor", {{"autosave", "sometimes"}}}}}},
+                "project.autosave");
+        rejects({{"revision", autosave_off.at("revision")},
+                 {"settings", {{"editor", {{"script_editor", {"other"}}}}}}},
+                "project.setting");
+        changed = commands.call("faset_project_settings_set",
+                                {{"revision", autosave_off.at("revision")},
+                                 {"settings", {{"editor", {{"autosave", true}}}}}});
+        session.poll();
+        require(commands.call("faset_autosave_status", Json::object()).at("enabled") == true,
+                "test", "Autosave enable must take effect in the current session");
         const auto setup = commands.call("faset_lua_setup", Json::object());
         require(setup.at("configuration_created") == true &&
                     setup.at("scripts_configuration_created") == true &&
@@ -115,6 +168,37 @@ int main() {
                        {{"path", "Scripts/behavior.lua"}, {"editor", {"{file}"}}}, "lua.editor");
         reject_command("faset_script_open", {{"path", "Scripts/behavior.lua"}, {"editor", {""}}},
                        "lua.editor");
+        const auto probe = root / "editor-argv.json";
+        const auto opened = commands.call(
+            "faset_source_open",
+            {{"path", "Scripts/Gameplay.cpp"}, {"line", 17}, {"column", 4},
+             {"editor", Json::array({path_to_utf8(std::filesystem::absolute(path_from_utf8(argv[0]))),
+                                     "--editor-probe", path_to_utf8(probe),
+                                     "{file}:{line}:{column}", "{project}"})}});
+        for (int attempt = 0; attempt < 100 && !std::filesystem::exists(probe); ++attempt)
+            std::this_thread::sleep_for(std::chrono::milliseconds(10));
+        const auto canonical_root = std::filesystem::weakly_canonical(root);
+        const auto expected_source = project_path(root, "Scripts/Gameplay.cpp");
+        const auto expected_arguments =
+            Json::array({path_to_utf8(expected_source) + ":17:4", path_to_utf8(canonical_root)});
+        const auto actual_arguments =
+            std::filesystem::is_regular_file(probe) ? read_json(probe) : Json(nullptr);
+        require(opened.at("path") == "Scripts/Gameplay.cpp" && opened.at("line") == 17 &&
+                    actual_arguments == expected_arguments,
+                "test", "Source navigation passes a Unicode path and location as literal argv; "
+                        "expected " + expected_arguments.dump() + ", got " +
+                        actual_arguments.dump());
+        reject_command("faset_source_open", {{"path", "../outside.cpp"}}, "source.path");
+        reject_command("faset_source_open", {{"path", "Scripts/missing.cpp"}}, "source.path");
+        reject_command("faset_source_open", {{"path", "Scripts"}}, "source.path");
+        atomic_write(root / "Scripts/tool.exe", "not a source\n");
+        reject_command("faset_source_open", {{"path", "Scripts/tool.exe"}}, "source.path");
+        std::filesystem::create_directories(root / "Outside");
+        std::error_code link_error;
+        std::filesystem::create_symlink(root / "Outside/secret.cpp",
+                                        root / "Scripts/escape.cpp", link_error);
+        if (!link_error)
+            reject_command("faset_source_open", {{"path", "Scripts/escape.cpp"}}, "source.path");
         auto bad_lua_project = session.project();
         bad_lua_project["scripting"] = {{"lua", {{"scripts", {"Scripts/missing.lua"}}}}};
         atomic_write_json(root / "project.faset.json", bad_lua_project);
@@ -122,6 +206,24 @@ int main() {
         require(invalid_lua_status.at("stale") == true &&
                     !invalid_lua_status.at("error").get<std::string>().empty(),
                 "test", "Invalid Lua manifest did not mark schema stale with diagnostics");
+        const auto autosave_id = document.at("id").get<std::string>();
+        const auto autosave_revision =
+            session.authoring().query(autosave_id).at("revision").get<std::uint64_t>();
+        session.authoring().transact(
+            autosave_id, autosave_revision,
+            Json::array({{{"op", "scene.rename"}, {"name", "Saved by MCP polling"}}}));
+        reject_command("faset_document_save",
+                       {{"document", autosave_id},
+                        {"expected_revision", autosave_revision}},
+                       "revision.conflict");
+        session.poll();
+        require(commands.call("faset_autosave_status", Json::object()).at("enabled") == true,
+                "test", "Autosave status is available through Editor commands");
+        std::this_thread::sleep_for(std::chrono::milliseconds(2100));
+        session.poll();
+        require(read_json(root / path_from_utf8("Scenes/Начало 世界.scene.json")).at("name") ==
+                    "Saved by MCP polling",
+                "test", "A long-lived headless Editor poll saves a named scene after idle");
         external["version"] = 999;
         atomic_write_json(root / "project.faset.json", external);
         bool rejected = false;
@@ -136,7 +238,16 @@ int main() {
                      "configuration preservation and Lua editor commands passed\n";
         return 0;
     } catch (const std::exception& error) {
-        std::cerr << error.what() << "\nFixture retained at " << root << '\n';
+        std::cerr << error.what() << "\nFixture retained at " << path_to_utf8(root) << '\n';
         return 1;
     }
 }
+#ifdef _WIN32
+int wmain(int argc, wchar_t** argv) {
+    return faset::run_utf8_main(argc, argv, test_main);
+}
+#else
+int main(int argc, char** argv) {
+    return test_main(argc, argv);
+}
+#endif

tests/editor_ui_latency.cpp

@@ -0,0 +1,70 @@
+#include <chrono>
+#include <cmath>
+#include <faset/core/io.hpp>
+#include <faset/editor/editor_ui.hpp>
+#include <iostream>
+#include <stdexcept>
+
+int main(int argc, char** argv) {
+    using namespace faset;
+    using Clock = std::chrono::steady_clock;
+    if (argc != 2) {
+        std::cerr << "Usage: faset_editor_ui_latency OUTPUT.json\n";
+        return 2;
+    }
+    const auto root = std::filesystem::temp_directory_path() /
+                      path_from_utf8("faset-ui-latency-" + new_id());
+    try {
+        std::filesystem::create_directories(root);
+        atomic_write_json(root / "project.faset.json",
+                          {{"format", "faset.project"},
+                           {"version", 1},
+                           {"name", "UI latency fixture"},
+                           {"dimension", 3}});
+        editor::Session session({root, path_from_utf8(FASET_TEST_ENGINE), root});
+        render::Renderer renderer({1280, 800, "Editor input latency", true, true});
+        editor::EditorUI ui(session, renderer,
+                            path_from_utf8(FASET_TEST_ENGINE) / "assets/fonts/NotoSans.ttf",
+                            path_from_utf8(FASET_TEST_ENGINE) / "assets/ui/dark.json");
+        ui.frame({});
+        Json samples = Json::array();
+        constexpr int warmup = 10, measured = 100;
+        for (int index = 0; index < warmup + measured; ++index) {
+            render::Event event;
+            event.type = render::Event::Type::KeyDown;
+            event.key = index % 2 == 0 ? "E" : "W";
+            const auto started = Clock::now();
+            ui.frame({event});
+            renderer.render(ui.snapshot());
+            const auto elapsed = std::chrono::duration<double, std::milli>(Clock::now() - started)
+                                     .count();
+            const auto target = index % 2 == 0 ? "gizmo-Rotate" : "gizmo-Move";
+            if (!ui.widgets().find(target)->selected ||
+                renderer.stats().validation_errors != 0 || !std::isfinite(elapsed) ||
+                elapsed <= 0)
+                throw std::runtime_error("Synthetic input was not visible in a valid frame");
+            if (index >= warmup)
+                samples.push_back({{"iteration", index - warmup + 1},
+                                   {"milliseconds", elapsed},
+                                   {"gizmo", event.key == "E" ? "Rotate" : "Move"}});
+        }
+        atomic_write_json(path_from_utf8(argv[1]),
+                          {{"format", "faset.editor-ui-latency"},
+                           {"version", 1},
+                           {"warmup_frames", warmup},
+                           {"measured_frames", measured},
+                           {"presentation_mode", "offscreen"},
+                           {"method", "KeyDown gizmo toggle through EditorUI::frame and "
+                                      "offscreen Vulkan render completion; no window present"},
+                           {"device", renderer.stats().device},
+                           {"validation_enabled", renderer.stats().validation_enabled},
+                           {"validation_errors", renderer.stats().validation_errors},
+                           {"samples", samples}});
+        std::filesystem::remove_all(root);
+        std::cout << "Measured " << measured << " synthetic Editor input frames\n";
+        return 0;
+    } catch (const std::exception& error) {
+        std::cerr << error.what() << "\nFixture: " << path_to_utf8(root) << '\n';
+        return 1;
+    }
+}

tests/editor_ui_launcher.cpp

@@ -111,6 +111,9 @@ int main() {
             text(launcher, "launcher-path", path_to_utf8(root / "." / new_project.filename()));
             click(launcher, "launcher-2d");
             check(launcher.widgets().find("launcher-2d")->selected, "2D project selection");
+            click(launcher, "launcher-lua");
+            check(launcher.widgets().find("launcher-lua")->selected,
+                  "Lua project language selection");
             renderer.render(launcher.snapshot());
             renderer.capture(root / "launcher-create.ppm");
             launcher.frame({key("Return", true)});
@@ -118,6 +121,7 @@ int main() {
                   "Create through keyboard rejected: " +
                       launcher.widgets().find("launcher-error")->text);
             check(launcher.selection()->create && launcher.selection()->dimension == 2 &&
+                      launcher.selection()->language == "lua" &&
                       launcher.selection()->name == "Тестовый проект",
                   "Create through keyboard preserves typed project metadata");
             check(launcher.selection()->path == new_project,
@@ -127,6 +131,19 @@ int main() {
             check(!std::filesystem::exists(new_project),
                   "Launcher does not create a partial project before Session scaffold");
         }
+        {
+            editor::ProjectSelection retry{new_project, "Retry starter", 3, true, "lua"};
+            editor::ProjectLauncher launcher(renderer, path_from_utf8(FASET_TEST_ENGINE), {},
+                                             recents, retry, "Template source is unavailable");
+            launcher.frame({});
+            check(launcher.widgets().find("launcher-create")->selected &&
+                      launcher.widgets().find("launcher-lua")->selected &&
+                      launcher.widgets().find("launcher-path")->text == path_to_utf8(new_project) &&
+                      launcher.widgets().find("launcher-name")->text == "Retry starter" &&
+                      launcher.widgets().find("launcher-error")->text ==
+                          "Template source is unavailable",
+                  "Failed starter returns to Create with the chosen options and error");
+        }
         {
             editor::ProjectLauncher launcher(renderer, path_from_utf8(FASET_TEST_ENGINE),
                                              root / "Missing", recents);

tests/editor_ui_project_settings.cpp

@@ -1,6 +1,8 @@
 #include <faset/core/io.hpp>
 #include <faset/editor/editor_ui.hpp>
+#include <chrono>
 #include <iostream>
+#include <thread>
 using namespace faset;
 namespace {
 void check(bool value, const std::string& message) {
@@ -50,6 +52,7 @@ int main() {
                                          {"id", new_id()},
                                          {"name", "Original project"},
                                          {"dimension", 3},
+                                         {"editor", {{"script_editor", {"zed", "{file}"}}}},
                                          {"custom_metadata", {{"preserve", true}}}});
         editor::Session session({root, path_from_utf8(FASET_TEST_ENGINE), root});
         render::Renderer renderer({1280, 800, "Project settings acceptance", true, true});
@@ -73,6 +76,13 @@ int main() {
         open(ui);
         check(ui.widgets().find("project-settings-name")->text == "Original project",
               "Opening settings reloads current saved values");
+        check(ui.widgets().find("project-settings-autosave")->checked,
+              "Missing autosave setting appears enabled in Project settings");
+        check(ui.widgets().focus("project-settings-autosave"),
+              "Keyboard focus reaches the Autosave toggle");
+        ui.frame({key("Space")});
+        check(!ui.widgets().find("project-settings-autosave")->checked,
+              "Space toggles Autosave from the keyboard");
         text(ui, "project-settings-name", "Новый проект");
         click(ui, "project-settings-2d");
         click(ui, "project-scene-choice-1");
@@ -81,11 +91,25 @@ int main() {
         click(ui, "project-settings-save");
         auto saved = read_json(project_file);
         check(saved["name"] == "Новый проект" && saved["dimension"] == 2 &&
-                  saved["start_scene"] == "Scenes/Другая.scene.json",
+                  saved["start_scene"] == "Scenes/Другая.scene.json" &&
+                  saved["editor"]["autosave"] == false,
               "Explicit Save project persists typed settings");
         check(saved["custom_metadata"] == project_before["custom_metadata"] &&
-                  saved["id"] == project_before["id"],
+                  saved["id"] == project_before["id"] &&
+                  saved["editor"]["script_editor"] ==
+                      project_before["editor"]["script_editor"],
               "Project settings preserve unknown metadata and project identity");
+        ui.frame({});
+        check(ui.widgets().find("autosave-status")->text == "Autosave off",
+              "Disabling Autosave is visible in the Editor status bar");
+        open(ui);
+        check(!ui.widgets().find("project-settings-autosave")->checked,
+              "Autosave preference is restored when reopening Project settings");
+        click(ui, "project-settings-autosave");
+        click(ui, "project-settings-save");
+        saved = read_json(project_file);
+        check(saved["editor"]["autosave"] == true,
+              "Autosave can be enabled again through Project settings");
         check(session.authoring().query(ui.current_document()) == document_before,
               "Project settings do not change current document, dimension, revision or Undo");
         open(ui);
@@ -118,6 +142,52 @@ int main() {
               "Save after explicit reload uses new content revision");
         check(session.authoring().query(ui.current_document()) == document_before,
               "Project settings remain outside scene Undo throughout conflicts");
+        const auto original_document = ui.current_document();
+        const auto revision =
+            session.authoring().query(original_document).at("revision").get<std::uint64_t>();
+        session.authoring().transact(
+            original_document, revision,
+            Json::array({{{"op", "scene.rename"}, {"name", "Pending autosave"}}}));
+        ui.frame({});
+        check(ui.widgets().find("autosave-status")->text == "Pending autosave",
+              "Status bar shows pending scene save after edit");
+        session.authoring().save(original_document);
+        ui.frame({});
+        check(ui.widgets().find("autosave-status")->text == "Saved",
+              "Status bar returns to Saved after the scene reaches disk");
+        session.authoring().transact(
+            original_document,
+            session.authoring().query(original_document).at("revision"),
+            Json::array({{{"op", "scene.rename"}, {"name", "Conflicting autosave"}}}));
+        ui.frame({});
+        const auto disk_path = root / path_from_utf8("Scenes/Главная.scene.json");
+        auto disk_scene = read_json(disk_path);
+        disk_scene["name"] = "External scene edit";
+        atomic_write_json(disk_path, disk_scene);
+        std::this_thread::sleep_for(std::chrono::milliseconds(2100));
+        ui.frame({});
+        check(ui.widgets().find("autosave-status")->text == "Save conflict" &&
+                  ui.widgets().find("autosave-status")->tooltip.find("Save As") !=
+                      std::string::npos,
+              "Disk conflict remains visible with Save As guidance");
+        renderer.render(ui.snapshot());
+        renderer.capture(root / "autosave-conflict.ppm");
+        check(ui.widgets().focus("autosave-save-as"),
+              "Keyboard focus reaches the recovery Save As action");
+        ui.frame({key("Return")});
+        check(ui.widgets().find("menu-popup")->visible &&
+                  ui.widgets().find("save-path")->visible,
+              "Recovery action opens an editable Save As path");
+        ui.frame({key("Escape")});
+        const auto unnamed = session.authoring().create("Unsaved", 2);
+        session.authoring().transact(
+            unnamed.at("id"), unnamed.at("revision"),
+            Json::array({{{"op", "scene.rename"}, {"name", "Needs a path"}}}));
+        ui.select_document(unnamed.at("id"));
+        ui.frame({});
+        check(ui.widgets().find("autosave-status")->text == "Save As required" &&
+                  ui.widgets().find("autosave-save-as")->visible,
+              "Unnamed dirty scene is never assigned an implicit path");
         open(ui);
         renderer.render(ui.snapshot());
         renderer.capture(root / "project-settings.ppm");

tests/measure_workflows_test.py

@@ -0,0 +1,80 @@
+"""Contracts for reproducible, honestly labelled P1 workflow measurements."""
+
+import importlib.util
+from pathlib import Path
+import unittest
+
+
+MODULE = Path(__file__).resolve().parents[1] / "tools/measure_workflows.py"
+SPEC = importlib.util.spec_from_file_location("measure_workflows", MODULE)
+workflows = importlib.util.module_from_spec(SPEC)
+SPEC.loader.exec_module(workflows)
+
+
+def report(samples):
+    return {
+        "format": "faset.workflow-measurements",
+        "version": 2,
+        "revision": "0123456789abcdef",
+        "source_hashes": {"Scripts/Gameplay.cpp": "a" * 64},
+        "build_configuration": "Debug",
+        "samples": samples,
+    }
+
+
+class WorkflowReportTests(unittest.TestCase):
+    def test_nearest_rank_summary(self):
+        self.assertEqual(workflows.summarize([1, 2, 3, 4, 5]),
+                         {"median": 3, "p95": 5})
+
+    def test_summary_rejects_empty_and_invalid_samples(self):
+        for values in ([], [0, -1], [1, float("nan")]):
+            with self.subTest(values=values), self.assertRaises(ValueError):
+                workflows.summarize(values)
+
+    def test_report_requires_revision_hashes_and_repetitions(self):
+        samples = {"warm_unchanged_build": [
+            {"seconds": 1.0, "build_configuration": "Debug", "source_hash": "a" * 64}
+            for _ in range(5)]}
+        workflows.validate_report(report(samples))
+        for mutation in (
+            lambda value: value.update(revision=""),
+            lambda value: value.update(source_hashes={}),
+            lambda value: value["samples"]["warm_unchanged_build"].pop(),
+            lambda value: value["samples"]["warm_unchanged_build"][0].update(
+                build_configuration="Release"),
+        ):
+            value = report({"warm_unchanged_build": [dict(sample) for sample in samples["warm_unchanged_build"]]})
+            mutation(value)
+            with self.subTest(value=value), self.assertRaises(ValueError):
+                workflows.validate_report(value)
+
+    def test_windowed_claim_rejects_offscreen_profile(self):
+        value = report({"windowed_first_presented_frame": [{
+            "seconds": 0.1, "build_configuration": "Debug",
+            "source_hash": "a" * 64, "presentation_mode": "offscreen"}]})
+        with self.assertRaises(ValueError):
+            workflows.validate_report(value)
+
+    def test_generated_scene_is_seeded_and_preserves_source(self):
+        scene = {"format": "faset.scene", "version": 1, "entities": [{
+            "id": "reference", "name": "Reference", "parent": None,
+            "components": [{"id": "transform", "type": "faset.transform", "version": 1,
+                            "fields": {"position": [0, 0, 0]}}]}]}
+        first = workflows.generate_scene_fixture(scene, seed=17, count=8)
+        second = workflows.generate_scene_fixture(scene, seed=17, count=8)
+        self.assertEqual(first, second)
+        self.assertEqual(len(first["entities"]), 9)
+        self.assertEqual(scene["entities"][0]["id"], "reference")
+        self.assertEqual(len({entry["id"] for entry in first["entities"]}), 9)
+        self.assertNotEqual(first, workflows.generate_scene_fixture(scene, seed=18, count=8))
+
+    def test_gnu_time_keeps_rss_after_expected_command_failure(self):
+        self.assertEqual(workflows.parse_peak_rss(
+            'Command exited with non-zero status 1\n{"peak_rss_kib":353272}\n'), 353272)
+        with self.assertRaises(ValueError):
+            workflows.parse_peak_rss("Command exited with non-zero status 1\n")
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/player_diagnostics_test.py

@@ -29,23 +29,6 @@ with tempfile.TemporaryDirectory(prefix="faset-player-diagnostics-") as temporar
     report = json.loads(profile.read_text(encoding="utf-8"))
     assert report["completed_frames"] == 1 and len(report["samples"]) == 1, report
     assert report["samples"][0]["tick"] == 1, report["samples"]
-    lighting = report["samples"][0]
-    assert lighting["effective_lighting_path"] == "forward", lighting
-    for field in ["submitted_local_lights", "omitted_local_lights",
-                  "requested_sun_cascades", "effective_sun_cascades",
-                  "requested_local_shadow_faces", "local_shadow_faces",
-                  "local_shadow_tiles", "dropped_shadow_faces",
-                  "dropped_point_shadow_faces", "shadow_atlas_full_drops",
-                  "shadow_caster_budget_drops", "shadow_unavailable_drops",
-                  "shadow_caster_draws", "sun_shadow_atlas_bytes",
-                  "local_shadow_atlas_bytes", "gpu_main_raster_ms",
-                  "gpu_sun_shadow_ms", "gpu_local_shadow_ms",
-                  "gpu_light_tiles_ms", "light_tile_count", "light_tile_counts_valid",
-                  "light_tile_candidate_count", "light_tile_overflow_count"]:
-        assert field in lighting, (field, lighting)
-    assert lighting["submitted_local_lights"] == 0 and \
-           lighting["effective_sun_cascades"] == 0 and \
-           lighting["local_shadow_faces"] == 0, lighting
 
     # The same linked v2 schema must validate without registering or invoking behavior.
     validated = subprocess.run([sys.argv[1], "--scene", str(scene), "--validate"],

tests/render_gpu_shader_contract_tests.cpp

@@ -59,15 +59,6 @@ int main() {
         faset::atomic_write_json(reflection_file, metadata);
         must_reject([&] { (void)faset::render::detail::load_gpu_shader_bundle(temporary); },
                     "A consistently rehashed but incompatible GPU record stride must be rejected");
-        faset::atomic_write_json(reflection_file,
-                                 faset::read_json(original / "gpuPostCullMain.reflection.json"));
-        reflection_file = temporary / "gpuVertexMain.reflection.json";
-        metadata = faset::read_json(original / "gpuVertexMain.reflection.json");
-        metadata["layout"]["descriptors"][0]["set"] = 1;
-        metadata["layout_fingerprint"] = faset::sha256(metadata["layout"].dump());
-        faset::atomic_write_json(reflection_file, metadata);
-        must_reject([&] { (void)faset::render::detail::load_gpu_shader_bundle(temporary); },
-                    "GPU graphics scene buffers must stay in descriptor set two");
         fs::remove(temporary / "gpuHzbMain.spv");
         must_reject([&] { (void)faset::render::detail::load_gpu_shader_bundle(temporary); },
                     "Missing P2 entry must be rejected");

tests/render_lighting_gpu_tests.cpp

@@ -1,403 +0,0 @@
-#include <faset/render/renderer.hpp>
-#include <algorithm>
-#include <cmath>
-#include <cstdint>
-#include <iostream>
-#include <stdexcept>
-#include <string>
-#include <vector>
-
-using namespace faset::render;
-namespace {
-void require(bool condition, const std::string& message) {
-    if (!condition)
-        throw std::runtime_error(message);
-}
-struct Frame {
-    std::vector<std::uint8_t> pixels;
-    FrameStats stats;
-};
-Frame capture(Renderer& renderer, const Snapshot& scene) {
-    renderer.render(scene);
-    return {renderer.pixels(), renderer.stats()};
-}
-Renderer make_renderer(VisibilityMode mode, LightingMode lighting = LightingMode::Auto) {
-    RendererConfig config;
-    config.width = 320;
-    config.height = 240;
-    config.headless = true;
-    config.validation = true;
-    config.visibility_mode = mode;
-    config.lighting_mode = lighting;
-    config.visibility_diagnostics = true;
-    return Renderer(config);
-}
-void compare_frames(const Frame& direct, const Frame& gpu) {
-    require(direct.pixels.size() == gpu.pixels.size(), "Lighting image dimensions match");
-    std::uint64_t error{};
-    std::size_t bad{};
-    for (std::size_t i = 0; i < direct.pixels.size(); i += 4) {
-        int worst{};
-        for (int channel = 0; channel < 3; ++channel) {
-            const int difference = std::abs(int(direct.pixels[i + channel]) -
-                                            int(gpu.pixels[i + channel]));
-            error += difference;
-            worst = std::max(worst, difference);
-        }
-        bad += worst > 16;
-    }
-    const auto count = direct.pixels.size() / 4;
-    require(bad <= std::max<std::size_t>(24, count / 200) &&
-                double(error) / double(count * 3) <= 2.0,
-            "Direct and GPU sun lighting images agree (bad=" + std::to_string(bad) +
-                ", mean=" + std::to_string(double(error) / double(count * 3)) + ")");
-}
-Snapshot scene(bool caster) {
-    Snapshot result;
-    result.view_id = "p3-offscreen-sun";
-    result.eye = {0, 5, 8};
-    const auto view = look_at(result.eye, {0, -1, 0});
-    const auto projection = orthographic(-2.5f, 2.5f, -2, 2, .1f, 50);
-    result.projection = projection;
-    result.view_projection = multiply(projection, view);
-    result.camera_frustum = CameraFrustum{view, projection, .1f, 50.f, false};
-    DrawItem receiver;
-    receiver.mesh = cube_mesh();
-    receiver.model = transform({0, -1, 0}, {}, {8, .1f, 8});
-    receiver.color = {.8f, .8f, .8f, 1};
-    receiver.instance_key = "receiver";
-    result.draws.push_back(receiver);
-    if (caster) {
-        DrawItem shadow_caster;
-        shadow_caster.mesh = cube_mesh();
-        shadow_caster.model = transform({3, 1, 0}, {}, {.8f, .8f, .8f});
-        shadow_caster.color = {.2f, .2f, .8f, 1};
-        shadow_caster.instance_key = "offscreen-caster";
-        result.draws.push_back(shadow_caster);
-    }
-    return result;
-}
-void sun() {
-    auto direct = make_renderer(VisibilityMode::Direct);
-    auto gpu = make_renderer(VisibilityMode::GpuFrustum);
-    auto occlusion = make_renderer(VisibilityMode::GpuOcclusion);
-    auto with_caster = scene(true);
-    const auto direct_frame = capture(direct, with_caster);
-    const auto gpu_frame = capture(gpu, with_caster);
-    const auto occlusion_frame = capture(occlusion, with_caster);
-    require(direct_frame.stats.effective_sun_cascades == 4 &&
-                gpu_frame.stats.effective_sun_cascades == 4 &&
-                occlusion_frame.stats.effective_sun_cascades == 4,
-            "Explicit 3D camera renders four sun cascades on every graphics path");
-    require(direct_frame.stats.requested_sun_cascades == 4 &&
-                direct_frame.stats.sun_shadow_caster_draws > 0 &&
-                direct_frame.stats.sun_shadow_caster_draws <= 4096 &&
-                direct_frame.stats.sun_shadow_atlas_bytes > 0 &&
-                direct_frame.stats.gpu_sun_shadow_ms > 0,
-            "Sun cascade stats describe bounded actual raster work and GPU time");
-    require(gpu_frame.stats.gpu_frustum_rejected > 0,
-            "Offscreen caster fixture is outside GPU camera frustum");
-    require(direct_frame.stats.validation_errors == 0 &&
-                gpu_frame.stats.validation_errors == 0 &&
-                occlusion_frame.stats.validation_errors == 0,
-            "Sun atlas rendering reports no Vulkan validation errors");
-    compare_frames(direct_frame, gpu_frame);
-    compare_frames(direct_frame, occlusion_frame);
-    auto without = scene(false);
-    const auto no_caster = capture(direct, without);
-    std::size_t darkened{};
-    for (std::size_t i = 0; i < direct_frame.pixels.size(); i += 4)
-        darkened += int(no_caster.pixels[i]) > int(direct_frame.pixels[i]) + 12;
-    require(darkened > 20,
-            "Offscreen source-LOD0 caster darkens visible receiver (count=" +
-                std::to_string(darkened) + ")");
-    auto coarser = with_caster;
-    auto degenerate_lod = std::make_shared<Mesh>(*cube_mesh());
-    for (auto& vertex : degenerate_lod->vertices)
-        vertex.position = {0, 0, 0};
-    coarser.draws.back().lod_meshes.push_back(degenerate_lod);
-    const auto source_lod_shadow = capture(gpu, coarser);
-    std::size_t lod_darkened{};
-    for (std::size_t i = 0; i < source_lod_shadow.pixels.size(); i += 4)
-        lod_darkened += int(no_caster.pixels[i]) >
-                        int(source_lod_shadow.pixels[i]) + 12;
-    require(source_lod_shadow.stats.lod_counts[1] > 0 && lod_darkened > 20,
-            "Shadow raster uses source LOD0 even when camera chooses a coarse LOD");
-    auto no_shadow = with_caster;
-    no_shadow.authored_lights_present = true;
-    no_shadow.sun = SunLight{"sun", no_shadow.light_direction, {1, 1, 1, 1}, 1, false};
-    const auto disabled = capture(direct, no_shadow);
-    require(disabled.stats.effective_sun_cascades == 0,
-            "Disabled sun shadow does no shadow raster work");
-    require(disabled.stats.sun_shadow_caster_draws == 0 &&
-                disabled.stats.gpu_sun_shadow_ms == 0,
-            "Disabled sun does not draw a hidden legacy shadow pass");
-    auto legacy = with_caster;
-    legacy.camera_frustum.reset();
-    const auto fallback = capture(direct, legacy);
-    require(fallback.stats.effective_sun_cascades == 1,
-            "Low-level snapshot without explicit camera retains one reported shadow view");
-    Snapshot sprite_only;
-    sprite_only.sprites.push_back({{0, 0, 0}, {1, 1}});
-    const auto two_d = capture(direct, sprite_only);
-    require(two_d.stats.effective_sun_cascades == 0,
-            "Sprite-only scene skips the sun atlas raster");
-    require(two_d.stats.sun_shadow_caster_draws == 0 &&
-                two_d.stats.gpu_sun_shadow_ms == 0,
-            "Sprite-only rendering spends no sun shadow GPU work");
-}
-Snapshot local_scene(LocalLight::Kind kind, bool caster_shadow) {
-    Snapshot result;
-    result.view_id = "p3-local-shadow";
-    result.eye = {0, 5, 8};
-    const auto view = look_at(result.eye, {0, -1, 0});
-    const auto projection = orthographic(-3, 3, -2.25f, 2.25f, .1f, 50);
-    result.projection = projection;
-    result.view_projection = multiply(projection, view);
-    result.camera_frustum = CameraFrustum{view, projection, .1f, 50, false};
-    result.authored_lights_present = true;
-    DrawItem floor;
-    floor.mesh = cube_mesh();
-    floor.model = transform({0, -1, 0}, {}, {8, .1f, 8});
-    floor.color = {.8f, .8f, .8f, 1};
-    floor.instance_key = "floor";
-    result.draws.push_back(floor);
-    DrawItem caster;
-    caster.mesh = cube_mesh();
-    caster.model = transform({0, .7f, 0}, {}, {.8f, .8f, .8f});
-    caster.color = {.4f, .4f, .4f, 1};
-    caster.cast_shadow = caster_shadow;
-    caster.instance_key = "caster";
-    result.draws.push_back(caster);
-    LocalLight light;
-    light.kind = kind;
-    light.stable_id = "local";
-    light.position = {0, 3, 0};
-    light.direction = {0, -1, 0};
-    light.color = {1, .85f, .65f, 1};
-    light.intensity = 80;
-    light.range = 8;
-    light.inner_angle = .3f;
-    light.outer_angle = .7f;
-    result.local_lights.push_back(light);
-    return result;
-}
-std::size_t darker_pixels(const Frame& shadowed, const Frame& unshadowed) {
-    std::size_t count{};
-    for (std::size_t i = 0; i < shadowed.pixels.size(); i += 4)
-        count += int(unshadowed.pixels[i]) > int(shadowed.pixels[i]) + 12;
-    return count;
-}
-Snapshot point_face_scene(Vec3 axis, bool caster_shadow) {
-    Snapshot result;
-    result.view_id = "point-six-faces";
-    const Vec3 lateral = std::abs(axis[1]) > .9f ? Vec3{0, 0, 1} : Vec3{0, 1, 0};
-    result.eye = {-axis[0] * .4f + lateral[0] * 2,
-                  -axis[1] * .4f + lateral[1] * 2,
-                  -axis[2] * .4f + lateral[2] * 2};
-    const Vec3 target{axis[0] * 3, axis[1] * 3, axis[2] * 3};
-    const auto view = look_at(result.eye, target);
-    const auto projection = orthographic(-2, 2, -2, 2, .1f, 20);
-    result.projection = projection;
-    result.view_projection = multiply(projection, view);
-    result.camera_frustum = CameraFrustum{view, projection, .1f, 20, false};
-    result.authored_lights_present = true;
-    DrawItem receiver;
-    receiver.mesh = cube_mesh();
-    receiver.model = transform(target, {}, {1.5f, 1.5f, 1.5f});
-    receiver.color = {.8f, .8f, .8f, 1};
-    receiver.instance_key = "point-receiver";
-    result.draws.push_back(receiver);
-    DrawItem caster;
-    caster.mesh = cube_mesh();
-    caster.model = transform({axis[0] * 1.5f, axis[1] * 1.5f, axis[2] * 1.5f},
-                             {}, {.5f, .5f, .5f});
-    caster.cast_shadow = caster_shadow;
-    caster.instance_key = "point-caster";
-    result.draws.push_back(caster);
-    LocalLight light;
-    light.stable_id = "point-face";
-    light.position = {0, 0, 0};
-    light.range = 8;
-    light.intensity = 90;
-    result.local_lights.push_back(light);
-    return result;
-}
-void local() {
-    auto direct = make_renderer(VisibilityMode::Direct);
-    auto gpu = make_renderer(VisibilityMode::GpuFrustum);
-    auto occlusion = make_renderer(VisibilityMode::GpuOcclusion);
-    for (auto kind : {LocalLight::Kind::Point, LocalLight::Kind::Spot}) {
-        const auto scene_with_shadow = local_scene(kind, true);
-        const auto shadowed = capture(direct, scene_with_shadow);
-        const auto gpu_shadowed = capture(gpu, scene_with_shadow);
-        const auto occlusion_shadowed = capture(occlusion, scene_with_shadow);
-        const auto unshadowed = capture(direct, local_scene(kind, false));
-        const auto faces = kind == LocalLight::Kind::Point ? 6u : 1u;
-        require(shadowed.stats.local_shadow_faces == faces &&
-                    shadowed.stats.requested_local_shadow_faces == faces &&
-                    shadowed.stats.shadow_caster_draws <= 4096 &&
-                    shadowed.stats.local_shadow_atlas_bytes > 0 &&
-                    shadowed.stats.gpu_local_shadow_ms > 0,
-                "Point/spot views render within atlas and caster budgets");
-        require(darker_pixels(shadowed, unshadowed) > 20,
-                "Caster darkens point/spot-lit receiver (count=" +
-                    std::to_string(darker_pixels(shadowed, unshadowed)) + ")");
-        require(shadowed.stats.validation_errors == 0 &&
-                    gpu_shadowed.stats.validation_errors == 0 &&
-                    occlusion_shadowed.stats.validation_errors == 0,
-                "Local shadow rendering passes Vulkan validation");
-        compare_frames(shadowed, gpu_shadowed);
-        compare_frames(shadowed, occlusion_shadowed);
-    }
-    for (const Vec3 axis : {Vec3{1, 0, 0}, Vec3{-1, 0, 0}, Vec3{0, 1, 0},
-                            Vec3{0, -1, 0}, Vec3{0, 0, 1}, Vec3{0, 0, -1},
-                            Vec3{.7071068f, .7071068f, 0}}) {
-        const auto shadowed = capture(direct, point_face_scene(axis, true));
-        const auto unshadowed = capture(direct, point_face_scene(axis, false));
-        require(shadowed.stats.local_shadow_faces == 6 &&
-                    darker_pixels(shadowed, unshadowed) > 5,
-                "A point light shadows each face direction and the adjacent-face seam");
-    }
-    auto crowded = local_scene(LocalLight::Kind::Point, true);
-    const auto point = crowded.local_lights.front();
-    crowded.local_lights.clear();
-    for (int i = 0; i < 15; ++i) {
-        LocalLight filler;
-        filler.kind = LocalLight::Kind::Spot;
-        filler.stable_id = "filler-" + std::to_string(i);
-        filler.position = {100, 100, 100};
-        filler.direction = {0, -1, 0};
-        filler.range = 8;
-        filler.intensity = 1;
-        filler.shadow_priority = 10;
-        crowded.local_lights.push_back(filler);
-    }
-    const auto without_point = capture(direct, crowded);
-    crowded.local_lights.push_back(point);
-    const auto overflow = capture(direct, crowded);
-    require(overflow.stats.requested_local_shadow_faces == 21 &&
-                overflow.stats.dropped_point_shadow_faces == 6 &&
-                overflow.stats.shadow_atlas_full_drops == 6 &&
-                overflow.stats.local_shadow_tiles <= 16,
-            "Fifteen occupied tiles drop the complete six-face point shadow");
-    std::size_t brightened{};
-    for (std::size_t i = 0; i < overflow.pixels.size(); i += 4)
-        brightened += int(overflow.pixels[i]) > int(without_point.pixels[i]) + 12;
-    require(brightened > 20,
-            "Point light with dropped atlas faces still illuminates unshadowed");
-}
-void tiled() {
-    for (auto visibility : {VisibilityMode::Direct, VisibilityMode::GpuFrustum,
-                            VisibilityMode::GpuOcclusion}) {
-        auto forward = make_renderer(visibility, LightingMode::Forward);
-        auto tiles = make_renderer(visibility, LightingMode::Tiled);
-        auto fixture = local_scene(LocalLight::Kind::Point, false);
-        auto no_lights = fixture;
-        no_lights.local_lights.clear();
-        const auto empty_tiled = capture(tiles, no_lights);
-        require(empty_tiled.stats.effective_lighting_path == "forward" &&
-                    empty_tiled.stats.light_tile_count == 0,
-                "Forced tiles correctly fall back when no local lights are submitted");
-        fixture.scene_rect = {32, 24, 256, 192};
-        fixture.local_lights.front().casts_shadow = false;
-        auto spot = fixture.local_lights.front();
-        spot.kind = LocalLight::Kind::Spot;
-        spot.stable_id = "second-spot";
-        spot.position = {1.5f, 2, 0};
-        spot.direction = {0, -1, 0};
-        spot.intensity = 7;
-        spot.range = 4;
-        fixture.local_lights.push_back(spot);
-        auto outside = spot;
-        outside.stable_id = "offscreen-light";
-        outside.position = {100, 100, 100};
-        outside.range = 2;
-        fixture.local_lights.push_back(outside);
-        const auto expected = capture(forward, fixture);
-        const auto actual = capture(tiles, fixture);
-        require(expected.stats.effective_lighting_path == "forward" &&
-                    actual.stats.effective_lighting_path == "tiled" &&
-                    actual.stats.gpu_light_tiles_ms > 0 &&
-                    actual.stats.light_tile_count > 0,
-                "Forced 16x16 tile construction reports its actual GPU work");
-        require(actual.stats.validation_errors == 0,
-                "Forward+ tile build and fragment reads pass Vulkan validation");
-        require(actual.stats.light_tile_overflow_count == 0 &&
-                    actual.stats.light_tile_candidate_count <
-                        actual.stats.light_tile_count * 3,
-                "Depth-free tile lists exclude an offscreen light without overflow");
-        compare_frames(expected, actual);
-
-        auto near_plane = local_scene(LocalLight::Kind::Point, true);
-        near_plane.local_lights.front().position = {0, 5, 7.95f};
-        near_plane.local_lights.front().range = 15;
-        const auto near_forward = capture(forward, near_plane);
-        const auto near_tiled = capture(tiles, near_plane);
-        require(near_tiled.stats.effective_lighting_path == "tiled" &&
-                    near_tiled.stats.light_tile_counts_valid,
-                "Near-plane crossing light and its shadow use actual tile lists");
-        compare_frames(near_forward, near_tiled);
-
-        forward.resize(336, 256);
-        tiles.resize(336, 256);
-        fixture.scene_rect = {40, 32, 248, 176};
-        const auto resized_forward = capture(forward, fixture);
-        const auto resized_tiled = capture(tiles, fixture);
-        require(resized_tiled.stats.light_tile_count == 21 * 16,
-                "Forward+ rebuilds its grid after a drawable resize");
-        compare_frames(resized_forward, resized_tiled);
-
-        // Eighty coincident lights cover the same central tiles. A 64-index tile
-        // must evaluate the entire submitted list instead of losing late lights.
-        fixture.local_lights.clear();
-        for (int i = 0; i < 80; ++i) {
-            auto light = point_face_scene({0, 0, 1}, false).local_lights.front();
-            light.stable_id = "overflow-" + std::to_string(i);
-            light.position = {0, 3, 0};
-            light.intensity = .45f;
-            light.range = 8;
-            light.casts_shadow = false;
-            fixture.local_lights.push_back(light);
-        }
-        const auto all_forward = capture(forward, fixture);
-        const auto all_tiled = capture(tiles, fixture);
-        auto automatic = make_renderer(visibility, LightingMode::Auto);
-        const auto dense_auto = capture(automatic, fixture);
-        require(dense_auto.stats.effective_lighting_path == "forward" &&
-                    dense_auto.stats.light_tile_count == 0,
-                "Auto avoids tile construction for unmeasured dense overlap");
-        require(all_tiled.stats.submitted_local_lights == 80 &&
-                    all_tiled.stats.effective_lighting_path == "tiled" &&
-                    all_tiled.stats.light_tile_overflow_count > 0,
-                "Overflow fixture submits all eighty lights through Forward+");
-        compare_frames(all_forward, all_tiled);
-        fixture.local_lights.resize(64);
-        const auto first_sixty_four = capture(forward, fixture);
-        std::size_t extra_light_pixels{};
-        for (std::size_t i = 0; i < all_forward.pixels.size(); i += 4)
-            extra_light_pixels += int(all_forward.pixels[i]) >
-                                  int(first_sixty_four.pixels[i]) + 2;
-        require(extra_light_pixels > 20,
-                "Overflow fixture visibly depends on lights past index 63");
-    }
-}
-} // namespace
-int main(int argc, char** argv) {
-    try {
-        if (argc != 2)
-            throw std::invalid_argument("Expected --sun, --local, or --tiled");
-        if (std::string(argv[1]) == "--sun")
-            sun();
-        else if (std::string(argv[1]) == "--local")
-            local();
-        else if (std::string(argv[1]) == "--tiled")
-            tiled();
-        else
-            throw std::invalid_argument("Expected --sun, --local, or --tiled");
-        std::cout << "Shadow atlas and Direct/GPU lighting parity passed\n";
-    } catch (const std::exception& error) {
-        std::cerr << error.what() << '\n';
-        return 1;
-    }
-}

tests/render_lighting_policy_tests.cpp

@@ -1,191 +0,0 @@
-#include <faset/render/lighting.hpp>
-#include <algorithm>
-#include <array>
-#include <cmath>
-#include <iostream>
-#include <stdexcept>
-
-using namespace faset::render;
-namespace {
-void require(bool condition, const char* message) {
-    if (!condition)
-        throw std::runtime_error(message);
-}
-Snapshot fixture() {
-    Snapshot frame;
-    const Vec3 eye{0, 2, 8};
-    const auto view = look_at(eye, {0, 0, 0});
-    const auto projection = perspective(.9f, 16.f / 9.f, .1f, 120.f);
-    frame.eye = eye;
-    frame.view_projection = multiply(projection, view);
-    frame.projection = projection;
-    frame.camera_frustum = CameraFrustum{view, projection, .1f, 120.f, true};
-    frame.authored_lights_present = true;
-    frame.sun = SunLight{"sun", {-.7f, -.5f, -.3f}, {1, 1, 1, 1}, 1, true};
-    return frame;
-}
-LocalLight point_light(std::string id, int priority = 0) {
-    LocalLight light;
-    light.kind = LocalLight::Kind::Point;
-    light.stable_id = std::move(id);
-    light.position = {0, 2, 0};
-    light.range = 12;
-    light.shadow_priority = priority;
-    return light;
-}
-LocalLight spot_light(std::string id, int priority = 0) {
-    auto light = point_light(std::move(id), priority);
-    light.kind = LocalLight::Kind::Spot;
-    light.direction = {0, -1, 0};
-    return light;
-}
-bool contains_caster(const ShadowView& view, std::uint32_t draw_index) {
-    return std::find(view.caster_indices.begin(), view.caster_indices.end(), draw_index) !=
-           view.caster_indices.end();
-}
-void run() {
-    auto frame = fixture();
-    const auto plan = build_shadow_plan(frame, {}, {});
-    require(plan.sun_views.size() == 4 && plan.effective_sun_cascades == 4,
-            "Explicit camera receives four usable sun cascades");
-    require(plan.sun_views[0].split_near == .1f &&
-                std::abs(plan.sun_views.back().split_far - 80.f) < 1e-4f,
-            "Practical splits start at camera near and stop at shadow distance");
-    for (std::size_t i = 1; i < plan.sun_views.size(); ++i)
-        require(plan.sun_views[i].split_near == plan.sun_views[i - 1].split_far &&
-                    plan.sun_views[i].split_far > plan.sun_views[i].split_near,
-                "Cascade split endpoints are strictly increasing and contiguous");
-    require(plan.sun_views[0].tile_index == 0 && plan.sun_views[3].tile_index == 3 &&
-                plan.sun_views[0].usable_size == 1020,
-            "Four guarded 1024-square tiles fit a 2048-square sun atlas");
-    auto shifted = frame;
-    shifted.eye[0] += .00001f;
-    const auto shifted_view = look_at(shifted.eye, {.00001f, 0, 0});
-    shifted.camera_frustum->view = shifted_view;
-    shifted.view_projection = multiply(shifted.projection, shifted_view);
-    const auto stable = build_shadow_plan(shifted, {}, {});
-    require(stable.sun_views[0].snapped_center_x == plan.sun_views[0].snapped_center_x &&
-                stable.sun_views[0].snapped_center_y == plan.sun_views[0].snapped_center_y,
-            "Subtexel camera translation retains the snapped sun projection origin");
-    const auto sun_direction = frame.sun->direction;
-    const auto inv_length = 1.f / std::hypot(sun_direction[0], sun_direction[1], sun_direction[2]);
-    const Vec3 upstream{-sun_direction[0] * inv_length * 18,
-                        -sun_direction[1] * inv_length * 18,
-                        -sun_direction[2] * inv_length * 18};
-    const ShadowCasterBounds offscreen{{{upstream[0] - .5f, upstream[1] - .5f,
-                                          upstream[2] - .5f},
-                                         {upstream[0] + .5f, upstream[1] + .5f,
-                                          upstream[2] + .5f}}, 7};
-    const ShadowCasterBounds outside{{{999, 0, 0}, {1001, 2, 2}}, 8};
-    const std::array casters{offscreen, outside};
-    const auto with_casters = build_shadow_plan(frame, casters, {});
-    require(std::any_of(with_casters.sun_views.begin(), with_casters.sun_views.end(),
-                        [](const auto& view) { return contains_caster(view, 7); }),
-            "Offscreen upstream caster remains in a receiver's sun shadow view");
-    require(std::none_of(with_casters.sun_views.begin(), with_casters.sun_views.end(),
-                         [](const auto& view) { return contains_caster(view, 8); }),
-            "Caster outside every sun XY footprint is excluded");
-    std::vector<ShadowCasterBounds> many(4097, {{{-.1f, -.1f, -.1f}, {.1f, .1f, .1f}}, 0});
-    for (std::uint32_t i = 0; i < many.size(); ++i)
-        many[i].draw_index = i;
-    const auto overdraw = build_shadow_plan(frame, many, {});
-    require(overdraw.caster_draws <= 4096 &&
-                std::any_of(overdraw.sun_views.begin(), overdraw.sun_views.end(),
-                            [](const auto& view) {
-                                return !view.valid && view.reason == ShadowDropReason::CasterBudget &&
-                                       view.caster_indices.empty();
-                            }),
-            "A view with 4097 casters is skipped whole rather than partially rendered");
-    frame.sun.reset();
-    for (int i = 0; i < 15; ++i)
-        frame.local_lights.push_back(spot_light("spot-" + std::to_string(i), 10));
-    frame.local_lights.push_back(point_light("last-point"));
-    const auto capacity = build_shadow_plan(frame, {}, {});
-    require(capacity.local_faces_used == 15 && capacity.dropped_point_faces == 6 &&
-                capacity.local_faces_used <= 16 && capacity.caster_draws <= 4096,
-            "Insufficient room for six point faces drops the complete point shadow");
-    require(capacity.submitted_local_indices.size() == 16 &&
-                std::none_of(capacity.local_views.begin(), capacity.local_views.end(),
-                             [](const auto& view) { return view.light_id == "last-point"; }),
-            "Atlas overflow leaves the point light in the lighting list, unshadowed");
-    frame.local_lights = {point_light("omnidirectional")};
-    const ShadowCasterBounds positive_x{{{3, -.2f, -.2f}, {3.4f, .2f, .2f}}, 19};
-    const auto point_faces = build_shadow_plan(frame, std::array{positive_x}, {});
-    require(point_faces.local_views.size() == 6 &&
-                contains_caster(point_faces.local_views[0], 19) &&
-                !contains_caster(point_faces.local_views[1], 19),
-            "Point-light caster behind the opposite face is culled from that face");
-    frame.local_lights.clear();
-    for (int i = 0; i < 15; ++i)
-        frame.local_lights.push_back(spot_light("spot-" + std::to_string(i), 10));
-    frame.local_lights.push_back(point_light("last-point"));
-    auto reversed = frame;
-    std::reverse(reversed.local_lights.begin(), reversed.local_lights.end());
-    const auto reordered = build_shadow_plan(reversed, {}, {});
-    require(reordered.local_views.size() == capacity.local_views.size(),
-            "Reversing input lights preserves scheduled view count");
-    for (std::size_t i = 0; i < capacity.local_views.size(); ++i)
-        require(reordered.local_views[i].light_id == capacity.local_views[i].light_id &&
-                    reordered.local_views[i].tile_index == capacity.local_views[i].tile_index,
-                "Stable IDs preserve atlas assignments across input reordering");
-    frame.local_lights.clear();
-    for (int i = 0; i < 128; ++i) {
-        auto light = spot_light("ordinary-" + std::to_string(i));
-        light.casts_shadow = false;
-        frame.local_lights.push_back(light);
-    }
-    auto important = spot_light("late-high-priority", 5);
-    important.casts_shadow = false;
-    frame.local_lights.push_back(important);
-    const auto ranked = build_shadow_plan(frame, {}, {});
-    require(ranked.submitted_local_indices.size() == 128 &&
-                ranked.omitted_local_lights == 1 &&
-                ranked.submitted_local_indices.front() == 128,
-            "Submission selects all 128 by priority and reports one omitted light");
-    frame.local_lights.back().range = -1;
-    bool invalid_overflow_rejected = false;
-    try {
-        (void)build_shadow_plan(frame, {}, {});
-    } catch (const std::invalid_argument&) {
-        invalid_overflow_rejected = true;
-    }
-    require(invalid_overflow_rejected,
-            "All authored lights are validated even when beyond the submission cap");
-    frame.local_lights.clear();
-    frame.sun.reset();
-    const auto no_sun = build_shadow_plan(frame, {}, {});
-    require(no_sun.requested_sun_cascades == 0 && no_sun.sun_views.empty(),
-            "Authored lights suppress legacy sun even when none is enabled");
-    for (int i = 0; i < 20; ++i)
-        frame.local_lights.push_back(spot_light("over-cap-" + std::to_string(i)));
-    ShadowBudget relaxed;
-    relaxed.max_local_faces = 64;
-    relaxed.max_local_lights = 256;
-    const auto clamped = build_shadow_plan(frame, {}, relaxed);
-    require(clamped.local_faces_used == 16 && clamped.dropped_local_faces == 4,
-            "Fixed 4x4 local atlas never allocates outside its sixteen tiles");
-    frame = fixture();
-    frame.camera_frustum.reset();
-    const auto legacy = build_shadow_plan(frame, {}, {});
-    require(legacy.sun_views.size() == 1 && legacy.effective_sun_cascades == 1,
-            "A low-level snapshot without camera frustum uses one reported sun view");
-    frame = fixture();
-    ShadowBudget unsupported;
-    unsupported.sun_atlas_available = false;
-    const auto no_atlas = build_shadow_plan(frame, {}, unsupported);
-    require(no_atlas.effective_sun_cascades == 0 &&
-                no_atlas.dropped_sun_views == 4 &&
-                no_atlas.sun_views[0].reason == ShadowDropReason::Unavailable,
-            "Unsupported depth atlas yields an explicit unshadowed sun fallback");
-}
-} // namespace
-int main() {
-    try {
-        run();
-        std::cout << "Shadow planning, stable allocation, caster visibility, and budgets passed\n";
-        return 0;
-    } catch (const std::exception& error) {
-        std::cerr << error.what() << '\n';
-        return 1;
-    }
-}

tests/render_reload_tests.cpp

@@ -46,7 +46,7 @@ int main() {
     try {
         const auto bundle = temporary / "shaders";
         fs::create_directories(bundle);
-        for (const auto* entry : {"vertexMain", "fragmentMain", "shadowMain", "lightTileMain",
+        for (const auto* entry : {"vertexMain", "fragmentMain", "shadowMain",
                                   "gpuVertexMain", "gpuShadowMain", "gpuCullMain",
                                   "gpuHzbMain", "gpuPostCullMain"})
             for (const auto* extension : {".spv", ".reflection.json"}) {
@@ -59,27 +59,6 @@ int main() {
         const auto original_reflection = read_text(bundle / "fragmentMain.reflection.json");
         const auto original_fingerprint = Json::parse(original_reflection).at("layout_fingerprint");
         render::validate_shader_bundle(bundle);
-        auto bad_lighting_stride = Json::parse(original_reflection);
-        auto& lighting_descriptors = bad_lighting_stride["layout"]["descriptors"];
-        bool found_local_buffer = false;
-        for (auto& descriptor : lighting_descriptors)
-            if (descriptor["set"] == 1 && descriptor["binding"] == 1) {
-                descriptor["element_stride"] = 96;
-                found_local_buffer = true;
-            }
-        require(found_local_buffer, "Lighting stride fixture exists");
-        bad_lighting_stride["layout_fingerprint"] =
-            sha256(bad_lighting_stride["layout"].dump());
-        atomic_write_json(bundle / "fragmentMain.reflection.json", bad_lighting_stride);
-        bool rejected_lighting_stride = false;
-        try {
-            render::validate_shader_bundle(bundle);
-        } catch (const std::exception&) {
-            rejected_lighting_stride = true;
-        }
-        require(rejected_lighting_stride,
-                "Rehashed incompatible local-light element stride must be rejected");
-        atomic_write(bundle / "fragmentMain.reflection.json", original_reflection);
         render::RendererConfig configuration;
         configuration.width = configuration.height = 64;
         configuration.headless = true;
@@ -88,7 +67,7 @@ int main() {
         render::Renderer renderer(configuration);
         const auto baseline_only = temporary / "baseline-only";
         fs::create_directories(baseline_only);
-        for (const auto* entry : {"vertexMain", "fragmentMain", "shadowMain", "lightTileMain"})
+        for (const auto* entry : {"vertexMain", "fragmentMain", "shadowMain"})
             for (const auto* extension : {".spv", ".reflection.json"}) {
                 const auto name = std::string(entry) + extension;
                 fs::copy_file(bundle / name, baseline_only / name);
@@ -126,40 +105,6 @@ int main() {
         opaque_scene.draws.push_back(opaque_cube);
         gpu_renderer.render(opaque_scene);
         const auto gpu_expected = gpu_renderer.pixels();
-        auto tiled_configuration = configuration;
-        tiled_configuration.lighting_mode = render::LightingMode::Tiled;
-        render::Renderer tiled_renderer(tiled_configuration);
-        auto lit_scene = opaque_scene;
-        render::LocalLight point;
-        point.stable_id = "reload-point";
-        point.position = {1, 1, 3};
-        point.intensity = 5;
-        point.range = 8;
-        point.casts_shadow = false;
-        lit_scene.local_lights.push_back(point);
-        tiled_renderer.render(lit_scene);
-        require(tiled_renderer.stats().effective_lighting_path == "tiled" &&
-                    tiled_renderer.stats().validation_errors == 0,
-                "Tiled lighting is active before shader reload");
-        const auto tiled_expected = tiled_renderer.pixels();
-        const auto original_tile_spirv = read_text(bundle / "lightTileMain.spv");
-        atomic_write(bundle / "lightTileMain.spv", "damaged tile bytecode");
-        std::string tile_error;
-        require(!tiled_renderer.reload_shaders(tile_error) && !tile_error.empty(),
-                "Rejected light tile shader preserves the working pipeline");
-        tiled_renderer.render(lit_scene);
-        require(tiled_renderer.stats().effective_lighting_path == "tiled" &&
-                    tiled_renderer.pixels() == tiled_expected &&
-                    tiled_renderer.stats().validation_errors == 0,
-                "Rejected light tile shader retains tiled lighting and pixels");
-        atomic_write(bundle / "lightTileMain.spv", original_tile_spirv);
-        require(tiled_renderer.reload_shaders(tile_error),
-                "Compatible light tile shader reloads successfully");
-        tiled_renderer.render(lit_scene);
-        require(tiled_renderer.stats().effective_lighting_path == "tiled" &&
-                    tiled_renderer.pixels() == tiled_expected &&
-                    tiled_renderer.stats().validation_errors == 0,
-                "Compatible light tile reload preserves tiled pixels");
         render::Snapshot scene;
         scene.ui_quads.push_back({0, 0, 32, 64, {1, .8f, .4f, 1}});
         scene.sprites.push_back({{.5f, 0, .5f}, {1, 2}, {.2f, 1, .4f, 1}});
@@ -173,7 +118,7 @@ int main() {
         require(deep_bundle.native().size() > 300,
                 "Shader file fixture must exceed the legacy Windows path limit");
         fs::create_directories(native_io_path(deep_bundle));
-        for (const auto* entry : {"vertexMain", "fragmentMain", "shadowMain", "lightTileMain",
+        for (const auto* entry : {"vertexMain", "fragmentMain", "shadowMain",
                                   "gpuVertexMain", "gpuShadowMain", "gpuCullMain",
                                   "gpuHzbMain", "gpuPostCullMain"})
             for (const auto* extension : {".spv", ".reflection.json"}) {
@@ -216,18 +161,6 @@ int main() {
         atomic_write(bundle / "fragmentMain.spv", "damaged bytecode");
         retained();
         restore();
-        auto incompatible = original_source;
-        auto at = incompatible.find("    float4 reserved;");
-        require(at != std::string::npos, "Local-light stride fixture exists");
-        incompatible.replace(at, std::string("    float4 reserved;").size(),
-                             "    float4 reserved;\n    float4 incompatibleExtraLane;");
-        atomic_write(source, incompatible);
-        require(compile(source, bundle) == 0, "Compile incompatible light-buffer stride");
-        require(read_json(bundle / "fragmentMain.reflection.json").at("layout_fingerprint") !=
-                    original_fingerprint,
-                "Lighting stride edit changes normalized layout fingerprint");
-        retained();
-        restore();
         auto malformed = original_spirv;
         for (int i = 0; i < 4; ++i)
             malformed[20 + i] = 0; // zero-word SPIR-V instruction
@@ -237,8 +170,8 @@ int main() {
         atomic_write_json(bundle / "fragmentMain.reflection.json", metadata);
         retained();
         restore();
-        incompatible = original_source;
-        at = incompatible.find("[[vk::binding(2,0)]]");
+        auto incompatible = original_source;
+        auto at = incompatible.find("[[vk::binding(2,0)]]");
         require(at != std::string::npos, "Shader descriptor fixture exists");
         incompatible.replace(at, std::string("[[vk::binding(2,0)]]").size(),
                              "[[vk::binding(7,0)]]");

tests/render_tests.cpp

@@ -134,102 +134,6 @@ int main(int argc, char** argv) {
         renderer.render(scene);
         pixels = renderer.pixels();
         require(pixels[index + 2] > 220, "Texture revision upload");
-        Snapshot two_lights;
-        two_lights.eye = {0, 0, 6};
-        two_lights.projection = perspective(.85f, 320.f / 240.f, .1f, 30.f);
-        two_lights.view_projection =
-            multiply(two_lights.projection, look_at(two_lights.eye, {0, 0, 0}));
-        two_lights.authored_lights_present = true;
-        two_lights.draws.push_back(
-            {cube_mesh(), transform({-1.4f, 0, 0}), {.5f, .5f, .5f, 1}, .6f, 0, false});
-        two_lights.draws.back().instance_key = "left-light-receiver";
-        two_lights.draws.push_back(
-            {cube_mesh(), transform({1.4f, 0, 0}), {.5f, .5f, .5f, 1}, .6f, 0, false});
-        two_lights.draws.back().instance_key = "right-light-receiver";
-        two_lights.ui_quads.push_back({8, 8, 40, 20, {.8f, .1f, .15f, 1}});
-        for (auto mode : {VisibilityMode::Direct, VisibilityMode::GpuFrustum}) {
-            renderer.set_visibility_mode(mode);
-            renderer.render(two_lights);
-            const auto dark = renderer.pixels();
-            require(renderer.stats().validation_errors == 0,
-                    "Zero-local-light descriptors are initialized");
-            auto legacy_lights = two_lights;
-            legacy_lights.authored_lights_present = false;
-            renderer.render(legacy_lights);
-            const auto legacy = renderer.pixels();
-            const auto left = (120 * 320 + 99) * 4;
-            require(legacy[left] > dark[left] + 15,
-                    "Authored-light presence suppresses the legacy sun even without a local light");
-            two_lights.local_lights = {
-                {LocalLight::Kind::Point, "red", {-1.4f, 0, 1.4f}, {0, 0, -1},
-                 {1, 0, 0, 1}, 8, 2.2f, .35f, .7f, false, 0},
-                {LocalLight::Kind::Point, "blue", {1.4f, 0, 1.4f}, {0, 0, -1},
-                {0, 0, 1, 1}, 8, 2.5f, .35f, .7f, false, 0}};
-            renderer.render(two_lights);
-            const auto lit = renderer.pixels();
-            const auto right = (120 * 320 + 221) * 4;
-            const auto ui = (10 * 320 + 10) * 4;
-            require(lit[left] > dark[left] + 20 && lit[right + 2] > dark[right + 2] + 20,
-                    "Separated red and blue point lights illuminate their receivers");
-            require(std::abs(int(lit[left + 2]) - int(dark[left + 2])) < 6 &&
-                        std::abs(int(lit[right]) - int(dark[right])) < 6,
-                    "Local light range keeps the opposite colored light off each receiver");
-            for (int channel = 0; channel < 4; ++channel)
-                require(lit[ui + channel] == dark[ui + channel],
-                        "Lighting changes leave UI tint unchanged");
-            require(renderer.stats().validation_errors == 0,
-                    "Direct and GPU local lighting report no Vulkan errors");
-            if (mode == VisibilityMode::GpuFrustum)
-                require(renderer.stats().effective_visibility_mode == VisibilityMode::GpuFrustum,
-                        "Local light image test actually exercises the GPU visibility path");
-            two_lights.local_lights[1].kind = LocalLight::Kind::Spot;
-            renderer.render(two_lights);
-            const auto aimed = renderer.pixels();
-            two_lights.local_lights[1].direction = {1, 0, 0};
-            renderer.render(two_lights);
-            const auto turned = renderer.pixels();
-            require(aimed[right + 2] > turned[right + 2] + 20,
-                    "Spotlight cone direction changes receiver illumination");
-            two_lights.local_lights.clear();
-        }
-        renderer.set_visibility_mode(VisibilityMode::Direct);
-        renderer.render(two_lights);
-        const auto unlit_overflow = renderer.pixels();
-        for (int i = 0; i < 128; ++i) {
-            LocalLight local;
-            local.stable_id = "low-priority-" + std::to_string(i);
-            local.position = {20, 20, 20};
-            local.range = 1;
-            local.intensity = 0;
-            local.casts_shadow = false;
-            two_lights.local_lights.push_back(local);
-        }
-        LocalLight high;
-        high.stable_id = "last-high-priority";
-        high.position = {-1.4f, 0, 1.4f};
-        high.color = {1, 0, 0, 1};
-        high.range = 2.2f;
-        high.intensity = 8;
-        high.shadow_priority = 10;
-        high.casts_shadow = false;
-        two_lights.local_lights.push_back(high);
-        two_lights.local_lights.back().range = -1;
-        bool overflow_validation_failed = false;
-        try {
-            renderer.render(two_lights);
-        } catch (const std::invalid_argument&) {
-            overflow_validation_failed = true;
-        }
-        require(overflow_validation_failed,
-                "Renderer validates light records beyond the 128-light cap");
-        two_lights.local_lights.back().range = 2.2f;
-        renderer.render(two_lights);
-        const auto ranked_pixels = renderer.pixels();
-        const auto ranked_left = (120 * 320 + 99) * 4;
-        require(renderer.stats().submitted_local_lights == 128 &&
-                    renderer.stats().omitted_local_lights == 1 &&
-                    ranked_pixels[ranked_left] > unlit_overflow[ranked_left] + 20,
-                "High-priority last light is submitted and omitted count is observable");
         if (argc > 2)
             renderer.capture(argv[2]);
         renderer.resize(400, 300);

tests/runtime_player_tests.cpp

@@ -1,12 +1,10 @@
 #include <bit>
-#include <algorithm>
 #include <cmath>
 #include <faset/assets/asset_pipeline.hpp>
 #include <faset/core/io.hpp>
 #include <faset/player/SceneView.hpp>
 #include <faset/runtime/Runtime.hpp>
 #include <iostream>
-#include <limits>
 #include <numbers>
 #include <stdexcept>
 
@@ -25,137 +23,12 @@ template <class F> void rejects(F&& function, const char* message) {
     }
     check(caught, message);
 }
-template <class F>
-void rejectsContaining(F&& function, std::string_view entityId, std::string_view field) {
-    try {
-        function();
-    } catch (const std::exception& error) {
-        const std::string_view what(error.what());
-        check(what.find(entityId) != std::string_view::npos &&
-                  what.find(field) != std::string_view::npos,
-              "Invalid light reports entity and field");
-        return;
-    }
-    throw std::runtime_error("Invalid light was accepted");
-}
 Json component(std::string type, Json fields) {
     return {{"id", type}, {"type", type}, {"version", 1}, {"fields", fields}};
 }
 Json entity(std::string id, Json parent, Json components) {
     return {{"id", id}, {"name", id}, {"parent", parent}, {"components", components}};
 }
-void lightingExtraction(faset::player::SceneView& view) {
-    auto scene = Json{{"format", "faset.scene"},
-                      {"version", 1},
-                      {"id", "lighting"},
-                      {"name", "Lighting"},
-                      {"dimension", 3},
-                      {"instances", Json::array()},
-                      {"entities", Json::array()}};
-    const auto empty = view.build(scene, 16.f / 9.f);
-    check(!empty.authored_lights_present && !empty.sun && empty.local_lights.empty(),
-          "Scene with no lights leaves legacy sun fallback available");
-    check(empty.camera_frustum && empty.camera_frustum->perspective &&
-              empty.camera_frustum->near_plane > 0 &&
-              empty.camera_frustum->far_plane > empty.camera_frustum->near_plane &&
-              faset::render::multiply(empty.camera_frustum->projection,
-                                      empty.camera_frustum->view) == empty.view_projection,
-          "3D extraction retains an unjittered camera frustum");
-    scene["entities"] = Json::array({
-        entity("sun", nullptr,
-               Json::array({component("faset.transform", {{"rotation", {0, .4, 0}}}),
-                            component("faset.light", {{"kind", "directional"},
-                                                      {"color", {1, .8, .6, 1}},
-                                                      {"intensity", 2.5},
-                                                      {"casts_shadow", false}})})),
-        entity("point", nullptr,
-               Json::array({component("faset.transform", {{"position", {2, 3, 4}}}),
-                            component("faset.light", {{"kind", "point"},
-                                                      {"color", {1, 0, 0, 1}},
-                                                      {"intensity", 4},
-                                                      {"range", 6},
-                                                      {"shadow_priority", 3}})})),
-        entity("spot", nullptr,
-               Json::array({component("faset.transform", {{"position", {-2, 1, 0}}}),
-                            component("faset.light", {{"kind", "spot"},
-                                                      {"color", {0, 0, 1, 1}},
-                                                      {"intensity", 3},
-                                                      {"range", 8},
-                                                      {"inner_angle", .2},
-                                                      {"outer_angle", .6}})}))});
-    const auto a = view.build(scene, 16.f / 9.f);
-    check(a.authored_lights_present && a.sun && a.local_lights.size() == 2,
-          "Directional, point, and spot lights survive extraction");
-    check(a.sun->color[1] == .8f && a.sun->intensity == 2.5f && !a.sun->casts_shadow,
-          "Authored sun properties survive extraction");
-    check(a.local_lights[0].kind == faset::render::LocalLight::Kind::Point &&
-              a.local_lights[0].position == faset::render::Vec3{2, 3, 4} &&
-              a.local_lights[0].range == 6 && a.local_lights[0].shadow_priority == 3,
-          "Point fields and transform survive extraction");
-    check(a.local_lights[1].kind == faset::render::LocalLight::Kind::Spot &&
-              a.local_lights[1].inner_angle == .2f && a.local_lights[1].outer_angle == .6f,
-          "Spot cone survives extraction");
-    std::reverse(scene["entities"].begin(), scene["entities"].end());
-    const auto b = view.build(scene, 16.f / 9.f);
-    check(a.sun->stable_id == b.sun->stable_id &&
-              a.local_lights[0].stable_id == b.local_lights[0].stable_id &&
-              a.local_lights[1].stable_id == b.local_lights[1].stable_id,
-          "Light identity and ordering ignore entity array order");
-    scene["entities"].erase(scene["entities"].begin() + 2);
-    const auto localOnly = view.build(scene, 1);
-    check(localOnly.authored_lights_present && !localOnly.sun &&
-              localOnly.local_lights.size() == 2,
-          "Local-only lighting does not synthesize a sun");
-    scene["entities"] = Json::array({entity(
-        "disabled-sun", nullptr,
-        Json::array({component("faset.light", {{"kind", "directional"}, {"enabled", false}})}))});
-    const auto disabled = view.build(scene, 1);
-    check(disabled.authored_lights_present && !disabled.sun && disabled.local_lights.empty(),
-          "Explicit disabled sun suppresses legacy fallback");
-    scene["entities"][0]["components"][0]["version"] = 2;
-    const auto future = view.build(scene, 1);
-    check(future.authored_lights_present && !future.sun,
-          "Opaque future-version light still suppresses legacy fallback");
-    scene["entities"] = Json::array({
-        entity("sun-z", nullptr, Json::array({component("faset.light", Json::object())})),
-        entity("sun-a", nullptr, Json::array({component("faset.light", Json::object())}))});
-    const auto twoSuns = view.build(scene, 1);
-    check(twoSuns.sun && twoSuns.sun->stable_id.find("sun-a") != std::string::npos,
-          "Multiple suns select lowest stable identity");
-    check(!view.diagnostics().empty() &&
-              view.diagnostics().front().find("directional") != std::string::npos,
-          "Additional directionals produce an actionable diagnostic");
-    scene["entities"] = Json::array({entity(
-        "bad-light", nullptr,
-        Json::array({component("faset.light", {{"kind", "point"}, {"range", 0}})}))});
-    rejectsContaining([&] { view.build(scene, 1); }, "bad-light", "range");
-    scene["entities"][0]["components"][0]["fields"] =
-        {{"kind", "spot"}, {"range", 10}, {"inner_angle", .8}, {"outer_angle", .2}};
-    rejectsContaining([&] { view.build(scene, 1); }, "bad-light", "inner_angle");
-    scene["entities"][0]["components"][0]["fields"] = {{"kind", "area"}};
-    rejectsContaining([&] { view.build(scene, 1); }, "bad-light", "kind");
-    scene["entities"][0]["components"][0]["fields"] =
-        {{"kind", "point"}, {"shadow_priority", std::int64_t{2147483648}}};
-    rejectsContaining([&] { view.build(scene, 1); }, "bad-light", "shadow_priority");
-    scene["entities"][0]["components"][0]["fields"] = {{"kind", "point"}};
-    scene["entities"][0]["components"].insert(
-        scene["entities"][0]["components"].begin(),
-        component("faset.transform", {{"scale", {1, 1, 0}}}));
-    const auto flatPoint = view.build(scene, 1);
-    check(flatPoint.local_lights.size() == 1 &&
-              flatPoint.local_lights[0].kind == faset::render::LocalLight::Kind::Point,
-          "Point light accepts a zero Z scale because it needs only a position");
-    scene["entities"][0]["components"].erase(scene["entities"][0]["components"].begin());
-    scene["entities"][0]["components"][0]["fields"] =
-        {{"kind", "point"},
-         {"color", Json::array({1, std::numeric_limits<double>::quiet_NaN(), 1, 1})}};
-    rejectsContaining([&] { view.build(scene, 1); }, "bad-light", "color");
-    scene["entities"][0]["components"].insert(
-        scene["entities"][0]["components"].begin(),
-        component("faset.transform", {{"position", {0, 0, 0}},
-                                       {"scale", Json::array({1, std::numeric_limits<double>::quiet_NaN(), 1})}}));
-    rejectsContaining([&] { view.build(scene, 1); }, "bad-light", "transform");
-}
 void physicsDebug(faset::player::SceneView& view) {
     for (int dimension : {2, 3}) {
         const std::string bodyName = dimension == 2 ? "rigid_body_2d" : "rigid_body_3d";
@@ -286,7 +159,6 @@ void run() {
     faset::atomic_write(folder / "version.fscene", version);
     rejects([&] { faset::player::readScene(folder / "version.fscene"); }, "reject cooked version");
     faset::player::SceneView view(folder);
-    lightingExtraction(view);
     physicsDebug(view);
     auto snapshot = view.build(scene, 16.f / 9.f);
     check(snapshot.draws.size() == 1, "SceneView builtin mesh");

tests/test_p3_lighting_benchmark.py

@@ -1,229 +0,0 @@
-"""Contract and arithmetic tests for the offline P3 lighting sweep wrapper."""
-
-import csv
-import json
-import subprocess
-import sys
-import tempfile
-import unittest
-from pathlib import Path
-
-
-ROOT = Path(__file__).resolve().parents[1]
-SCRIPT = ROOT / "tools/benchmark_p3_lighting.py"
-sys.path.insert(0, str(ROOT / "tools"))
-
-
-def sample(shadows, visibility, lights, raster, gpu, repeat=1, frame=0):
-    return {
-        "shadows": shadows, "visibility": visibility, "light_count": str(lights),
-        "run_index": str(repeat), "frame": str(frame),
-        "gpu_main_raster_ms": str(raster), "gpu_ms": str(gpu),
-        "gpu_shadow_ms": "0", "cpu_ms": "1", "readback_cpu_ms": ".5",
-        "validation_errors": "0", "device": "Fake GPU", "driver": "Fake Driver",
-        "commit": "abc123", "effective_visibility": visibility,
-        "lighting_path": "forward", "submitted_local_lights": str(lights),
-        "omitted_local_lights": "0", "shadow_tiles": "0", "draw_calls": "1",
-        "gpu_bytes": "4096", "validation_enabled": "0", "width": "1920", "height": "1080",
-    }
-
-
-FAKE_BENCHMARK = r'''import argparse
-import csv
-import json
-from pathlib import Path
-
-p = argparse.ArgumentParser()
-for flag in ("lights", "run-index", "width", "height", "warmup", "frames"):
-    p.add_argument("--" + flag, type=int, required=True)
-for flag in ("shadows", "visibility", "csv", "commit", "validation"):
-    p.add_argument("--" + flag, required=True)
-p.add_argument("--driver")
-a = p.parse_args()
-path = Path(a.csv)
-path.with_suffix(".args.json").write_text(json.dumps(vars(a)), encoding="utf-8")
-fieldnames = ["light_count", "shadows", "visibility", "frame", "device", "driver",
-              "commit", "gpu_main_raster_ms", "gpu_ms", "gpu_shadow_ms", "cpu_ms",
-              "readback_cpu_ms", "validation_errors", "run_index", "effective_visibility",
-              "lighting_path", "submitted_local_lights", "omitted_local_lights",
-              "shadow_tiles", "draw_calls", "gpu_bytes", "validation_enabled", "width", "height"]
-with path.open("w", newline="", encoding="utf-8") as stream:
-    writer = csv.DictWriter(stream, fieldnames=fieldnames)
-    writer.writeheader()
-    for frame in range(a.frames):
-        writer.writerow(dict(light_count=a.lights, shadows=a.shadows,
-                             visibility=a.visibility, frame=frame, device="Fake GPU",
-                             driver="Fake Driver", commit=a.commit,
-                             gpu_main_raster_ms=.4 + .02 * a.lights, gpu_ms=4 + .02 * a.lights,
-                             gpu_shadow_ms=0, cpu_ms=1, readback_cpu_ms=.5,
-                             validation_errors=0, run_index=a.run_index,
-                             effective_visibility=a.visibility, lighting_path="forward",
-                             submitted_local_lights=a.lights, omitted_local_lights=0,
-                             shadow_tiles=0, draw_calls=1, gpu_bytes=4096,
-                             validation_enabled=0, width=a.width, height=a.height))
-'''
-
-
-class LightingBenchmarkTests(unittest.TestCase):
-    def test_list_runs_has_three_independent_repeats_for_each_shadow_setting(self):
-        process = subprocess.run([sys.executable, SCRIPT, "--list-runs"],
-                                 text=True, capture_output=True, check=True)
-        runs = json.loads(process.stdout)["runs"]
-        self.assertEqual(len(runs), 108)
-        for shadows in ("off", "on"):
-            group = [run for run in runs if run["shadows"] == shadows]
-            self.assertEqual(len(group), 54)
-            self.assertEqual({(run["light_count"], run["visibility"])
-                              for run in group},
-                             {(light, mode) for light in (0, 4, 16, 32, 64, 128)
-                              for mode in ("direct", "gpu-frustum", "gpu-occlusion")})
-            self.assertEqual({(run["light_count"], run["visibility"], run["repeat"])
-                              for run in group},
-                             {(light, mode, repeat)
-                              for light in (0, 4, 16, 32, 64, 128)
-                              for mode in ("direct", "gpu-frustum", "gpu-occlusion")
-                              for repeat in (1, 2, 3)})
-
-    def test_gate_uses_per_run_medians_and_same_mode_shadow_baseline(self):
-        from benchmark_p3_lighting import summarize_rows
-
-        rows = []
-        for repeat in (1, 2, 3):
-            for frame in (0, 1, 2):
-                rows.append(sample("off", "direct", 0, .5, 10, repeat, frame))
-                rows.append(sample("off", "direct", 32,
-                                   100 if repeat == 3 else 1.5, 11, repeat, frame))
-                rows.append(sample("on", "gpu-frustum", 0, .5, 4, repeat, frame))
-                rows.append(sample("on", "gpu-frustum", 64, 1.1, 4.6, repeat, frame))
-                rows.append(sample("off", "gpu-occlusion", 0, .5, 4, repeat, frame))
-                rows.append(sample("off", "gpu-occlusion", 128, 1.09, 4.59, repeat, frame))
-        summary = summarize_rows(rows)
-        hits = {(item["shadows"], item["visibility"], item["light_count"]): item
-                for item in summary["forward_plus_gate"]["candidates"]}
-        self.assertEqual(set(hits), {("off", "direct", 32),
-                                     ("on", "gpu-frustum", 64)})
-        self.assertAlmostEqual(hits[("off", "direct", 32)]["overhead_ms"], 1.0)
-        self.assertAlmostEqual(hits[("on", "gpu-frustum", 64)]["overhead_ms"], .6)
-        self.assertEqual(hits[("off", "direct", 32)]["zero_light_gpu_ms"], 10)
-        self.assertEqual(hits[("on", "gpu-frustum", 64)]["zero_light_gpu_ms"], 4)
-
-    def test_sweep_runs_fake_executable_and_preserves_all_raw_frames(self):
-        with tempfile.TemporaryDirectory() as temporary:
-            root = Path(temporary)
-            fake = root / "fake_benchmark.py"
-            fake.write_text(FAKE_BENCHMARK, encoding="utf-8")
-            output = root / "café 世界"
-            process = subprocess.run(
-                [sys.executable, SCRIPT, "--sweep", "--executable", fake,
-                 "--output", output, "--shadows", "off", "--commit", "abc123",
-                 "--driver", "Fake Driver"],
-                text=True, capture_output=True)
-            self.assertEqual(process.returncode, 0, process.stderr)
-            raw = list((output / "raw").glob("*.csv"))
-            self.assertEqual(len(raw), 54)
-            with (output / "merged.csv").open(newline="", encoding="utf-8") as stream:
-                merged = list(csv.DictReader(stream))
-            self.assertEqual(len(merged), 54 * 30)
-            self.assertEqual({row["source_csv"] for row in merged},
-                             {path.name for path in raw})
-            report = json.loads((output / "summary.json").read_text(encoding="utf-8"))
-            self.assertEqual(report["runs_completed"], 54)
-            self.assertEqual(report["rows"], 54 * 30)
-            self.assertTrue(report["forward_plus_gate"]["triggered"])
-            one = json.loads(next((output / "raw").glob("*.args.json")).read_text())
-            self.assertEqual((one["width"], one["height"], one["warmup"], one["frames"]),
-                             (1920, 1080, 10, 30))
-            self.assertEqual(one["validation"], "off")
-
-    def test_sweep_rejects_missing_gpu_raster_column(self):
-        with tempfile.TemporaryDirectory() as temporary:
-            root = Path(temporary)
-            fake = root / "bad_benchmark.py"
-            fake.write_text(FAKE_BENCHMARK.replace(
-                '"gpu_main_raster_ms", "gpu_ms"', '"gpu_ms"').replace(
-                'gpu_main_raster_ms=.4 + .02 * a.lights, ', ''), encoding="utf-8")
-            output = root / "invalid"
-            process = subprocess.run(
-                [sys.executable, SCRIPT, "--sweep", "--executable", fake,
-                 "--output", output, "--shadows", "off", "--commit", "abc123",
-                 "--driver", "Fake Driver"],
-                text=True, capture_output=True)
-            self.assertNotEqual(process.returncode, 0)
-            self.assertIn("gpu_main_raster_ms", process.stderr)
-            self.assertFalse((output / "summary.json").exists())
-
-    def test_sweep_rejects_visibility_fallback_as_a_mode_measurement(self):
-        with tempfile.TemporaryDirectory() as temporary:
-            root = Path(temporary)
-            fake = root / "fallback.py"
-            fake.write_text(FAKE_BENCHMARK.replace(
-                'effective_visibility=a.visibility', 'effective_visibility="direct"'),
-                encoding="utf-8")
-            output = root / "fallback-output"
-            process = subprocess.run(
-                [sys.executable, SCRIPT, "--sweep", "--executable", fake,
-                 "--output", output, "--shadows", "off", "--commit", "abc123",
-                 "--driver", "Fake Driver"],
-                text=True, capture_output=True)
-            self.assertNotEqual(process.returncode, 0)
-            self.assertIn("effective_visibility", process.stderr)
-            self.assertFalse((output / "summary.json").exists())
-
-    def test_sweep_rejects_a_scene_that_does_not_submit_requested_lights(self):
-        with tempfile.TemporaryDirectory() as temporary:
-            root = Path(temporary)
-            fake = root / "wrong-count.py"
-            fake.write_text(FAKE_BENCHMARK.replace(
-                'submitted_local_lights=a.lights', 'submitted_local_lights=0'),
-                encoding="utf-8")
-            output = root / "wrong-count-output"
-            process = subprocess.run(
-                [sys.executable, SCRIPT, "--sweep", "--executable", fake,
-                 "--output", output, "--shadows", "off", "--commit", "abc123",
-                 "--driver", "Fake Driver"],
-                text=True, capture_output=True)
-            self.assertNotEqual(process.returncode, 0)
-            self.assertIn("submitted_local_lights", process.stderr)
-            self.assertFalse((output / "summary.json").exists())
-
-    def test_sweep_requires_known_driver_identity(self):
-        from benchmark_p3_lighting import sweep
-        with tempfile.TemporaryDirectory() as temporary:
-            fake = Path(temporary) / "fake.py"
-            fake.write_text(FAKE_BENCHMARK, encoding="utf-8")
-            with self.assertRaisesRegex(ValueError, "--driver"):
-                sweep(fake, Path(temporary) / "out", "off", "abc123")
-
-
-def real_executable_smoke(executable: Path) -> None:
-    from benchmark_p3_lighting import REQUIRED_COLUMNS
-
-    choices = subprocess.run([executable, "--list-runs"], capture_output=True,
-                             text=True, check=True)
-    declared = json.loads(choices.stdout)
-    if declared["lights"] != [0, 4, 16, 32, 64, 128] or len(declared["visibility"]) != 3:
-        raise AssertionError("C++ executable and Python sweep matrix disagree")
-    with tempfile.TemporaryDirectory() as directory:
-        output = Path(directory) / "café 世界" / "smoke.csv"
-        subprocess.run([executable, "--lights", "4", "--shadows", "off",
-                        "--visibility", "direct", "--width", "64", "--height", "64",
-                        "--warmup", "0", "--frames", "1", "--validation", "on",
-                        "--commit", "smoke", "--driver", "smoke-driver",
-                        "--csv", output], capture_output=True, text=True, check=True)
-        with output.open(newline="", encoding="utf-8") as stream:
-            reader = csv.DictReader(stream)
-            columns, rows = reader.fieldnames or [], list(reader)
-        if set(REQUIRED_COLUMNS) - set(columns) or len(rows) != 1:
-            raise AssertionError("Real benchmark CSV lacks a complete single-frame row")
-        row = rows[0]
-        if (row["effective_visibility"] != "direct" or row["lighting_path"] != "forward" or
-                row["submitted_local_lights"] != "4" or row["validation_errors"] != "0" or
-                float(row["gpu_main_raster_ms"]) <= 0):
-            raise AssertionError("Real benchmark did not report the measured lighting path")
-
-
-if __name__ == "__main__":
-    if len(sys.argv) == 3 and sys.argv[1] == "--real-executable":
-        real_executable_smoke(Path(sys.argv[2]).resolve())
-    else:
-        unittest.main()

tests/test_shader_reflection.py

@@ -36,55 +36,6 @@ def parameter(name: str, index: int, shape: str, access: str, stride: int | None
 
 
 class ReflectionTests(unittest.TestCase):
-    def test_graphics_lighting_abi(self):
-        compiler = os.environ["FASET_TEST_SLANGC"]
-        with tempfile.TemporaryDirectory(prefix="faset-lighting-abi-") as directory:
-            for source, entry, defines in (
-                ("baseline.slang", "fragmentMain", []),
-                ("gpu_scene.slang", "gpuVertexMain", ["--define", "FASET_GPU_GRAPHICS=1"]),
-            ):
-                process = subprocess.run(
-                    [sys.executable, str(SCRIPT), "--compiler", compiler, "--source",
-                     str(SCRIPT.parents[1] / "shaders" / source), "--entry", entry,
-                     *defines, "--output", directory],
-                    capture_output=True, text=True,
-                )
-                self.assertEqual(process.returncode, 0, process.stderr)
-            fragment = json.loads((Path(directory) / "fragmentMain.reflection.json").read_text())
-            gpu_vertex = json.loads((Path(directory) / "gpuVertexMain.reflection.json").read_text())
-            lighting = {
-                (d["set"], d["binding"]): (d["type"], d.get("element_stride"))
-                for d in fragment["layout"]["descriptors"]
-            }
-            self.assertEqual([lighting[1, i] for i in range(5)],
-                             [("storage_buffer", 80), ("storage_buffer", 80),
-                              ("storage_buffer", 112), ("sampled_image_2d", None),
-                              ("storage_buffer", 4)])
-            graphics = {
-                (d["set"], d["binding"]): d["element_stride"]
-                for d in gpu_vertex["layout"]["descriptors"]
-            }
-            self.assertEqual([graphics[2, i] for i in range(3)], [224, 4, 208])
-
-    def test_light_tile_compute_reflection(self):
-        compiler = os.environ["FASET_TEST_SLANGC"]
-        with tempfile.TemporaryDirectory(prefix="faset-light-tiles-abi-") as directory:
-            process = subprocess.run(
-                [sys.executable, str(SCRIPT), "--compiler", compiler, "--source",
-                 str(SCRIPT.parents[1] / "shaders" / "light_tiles.slang"), "--entry",
-                 "lightTileMain", "--output", directory],
-                capture_output=True, text=True,
-            )
-            self.assertEqual(process.returncode, 0, process.stderr)
-            layout = json.loads((Path(directory) / "lightTileMain.reflection.json").read_text())["layout"]
-            self.assertEqual(layout["stage"], "compute")
-            self.assertEqual(
-                [(item["set"], item["binding"], item["type"], item.get("element_stride"))
-                 for item in layout["descriptors"]],
-                [(0, 0, "storage_buffer", 80), (0, 1, "storage_buffer", 4)],
-            )
-            self.assertEqual(layout["push_constants"][0]["size"], 96)
-
     def test_gpu_vertex_paths_do_not_require_shader_draw_parameters(self):
         # SV_InstanceID makes Slang subtract BaseInstance and emit DrawParameters.
         # Our indirect commands always use firstInstance=0, so the Vulkan instance

tests/verify_playable_exports_test.py

@@ -0,0 +1,105 @@
+"""Small contract checks for the cross-platform export verifier's Lua mode."""
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "tools"))
+from verify_playable_exports import (device_class, project_matrix, project_workspace,
+                                     sha256, verify_capture, verify_lua_export,
+                                     verify_lua_execution, verify_package,
+                                     vulkan_device_details)
+
+
+class ExportProjectMatrixTests(unittest.TestCase):
+    def test_native_project_workspace_is_outside_engine(self):
+        with tempfile.TemporaryDirectory() as directory:
+            engine = Path(directory) / "engine"
+            engine.mkdir()
+            internal_output = engine / ".cache" / "exports"
+            workspace = project_workspace(engine, internal_output)
+            try:
+                self.assertFalse(workspace.is_relative_to(engine))
+            finally:
+                workspace.rmdir()
+            external_output = Path(directory) / "evidence"
+            self.assertEqual(project_workspace(engine, external_output), external_output)
+
+    def test_lua_is_explicit_and_can_run_alone(self):
+        self.assertEqual([name for name, _, _ in project_matrix(False, False)],
+                         ["collect-2d", "collect-3d"])
+        self.assertEqual([name for name, _, _ in project_matrix(True, False)],
+                         ["collect-2d", "collect-3d", "lua"])
+        self.assertEqual(project_matrix(False, True), [("lua", 2, "lua")])
+
+    def test_lua_package_requires_source_and_license_without_cpp_stub(self):
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            (root / "Scripts").mkdir()
+            (root / "Notices/lua").mkdir(parents=True)
+            (root / "Scripts/player.lua").write_text("return {}\n", encoding="utf-8")
+            (root / "Notices/lua/LICENSE.txt").write_text("License\n", encoding="utf-8")
+            manifest = {"lua_enabled": True, "files": [
+                {"path": "Scripts/player.lua"}, {"path": "Notices/lua/LICENSE.txt"}]}
+            verify_lua_export(root, manifest)
+            with self.assertRaisesRegex(RuntimeError, "license"):
+                verify_lua_export(root, {**manifest, "files": manifest["files"][:1]})
+            (root / "Scripts/GameplayExtra.cpp").write_text("// stray\n", encoding="utf-8")
+            manifest["files"].append({"path": "Scripts/GameplayExtra.cpp"})
+            with self.assertRaisesRegex(RuntimeError, "C\\+\\+"):
+                verify_lua_export(root, manifest)
+            (root / "Scripts/GameplayExtra.cpp").unlink()
+            manifest["files"].pop()
+            (root / "Notices/lua/LICENSE.txt").unlink()
+            with self.assertRaisesRegex(RuntimeError, "license"):
+                verify_lua_export(root, manifest)
+
+    def test_lua_capture_requires_its_small_scene_palette(self):
+        with tempfile.TemporaryDirectory() as directory:
+            path = Path(directory) / "capture.ppm"
+            header = b"P6\n4 1\n255\n"
+            path.write_bytes(header + bytes.fromhex("0e1116334c6633bfe5ffb233"))
+            self.assertEqual(verify_capture(path, language="lua")["sampled_colors"], 4)
+            with self.assertRaisesRegex(RuntimeError, "geometry/colors"):
+                verify_capture(path)
+            path.write_bytes(header + bytes.fromhex("0e1116334c6633bfe5334c66"))
+            with self.assertRaisesRegex(RuntimeError, "geometry/colors"):
+                verify_capture(path, language="lua")
+
+    def test_driver_probe_selects_the_rendering_device(self):
+        summary = ("GPU0:\n deviceName = llvmpipe\n driverName = Mesa\n"
+                   "GPU1:\n deviceName = Discrete GPU\n driverVersion = 123\n"
+                   " driverName = Vendor\n driverInfo = 1.2.3\n")
+        self.assertEqual(vulkan_device_details(summary, "Discrete GPU"),
+                         {"deviceName": "Discrete GPU", "driverVersion": "123",
+                          "driverName": "Vendor", "driverInfo": "1.2.3"})
+        self.assertEqual(vulkan_device_details(summary, "Unknown"), {})
+        self.assertEqual(device_class("SwiftShader Device", {}), "software")
+        self.assertEqual(device_class("NVIDIA GeForce RTX 2080 Ti", {}), "physical")
+        self.assertEqual(device_class("Mystery Device", {}), "unknown")
+
+    def test_package_rejects_undeclared_file(self):
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            (root / "Scripts").mkdir()
+            (root / "Scripts/player.lua").write_text("return {}\n", encoding="utf-8")
+            file = root / "Scripts/player.lua"
+            manifest = {"format": "faset.export", "version": 1,
+                        "configuration": "Release", "files": [
+                            {"path": "Scripts/player.lua", "size": file.stat().st_size,
+                             "sha256": sha256(file)}]}
+            import json
+            (root / "manifest.json").write_text(json.dumps(manifest), encoding="utf-8")
+            verify_package(root)
+            (root / "Scripts/GameplayExtra.cpp").write_text("// stray\n", encoding="utf-8")
+            with self.assertRaisesRegex(RuntimeError, "undeclared"):
+                verify_package(root)
+
+    def test_lua_execution_requires_on_start_marker(self):
+        verify_lua_execution("Lua player ready: A/D move, Space jump, E reset\n")
+        with self.assertRaisesRegex(RuntimeError, "on_start"):
+            verify_lua_execution("")
+
+
+if __name__ == "__main__":
+    unittest.main()

tools/benchmark_p3_lighting.py

@@ -1,262 +0,0 @@
-#!/usr/bin/env python3
-"""Run the fixed P3 lighting sweep and retain raw per-frame GPU measurements.
-
-The Forward+ threshold in the summary is a measurement result, not an automatic
-renderer switch. Apply it to the Linux physical reference GPU; keep other devices
-as separate functional/performance observations.
-"""
-from __future__ import annotations
-
-import argparse
-import csv
-import json
-import math
-from pathlib import Path
-import statistics
-import subprocess
-import sys
-
-
-LIGHT_COUNTS = (0, 4, 16, 32, 64, 128)
-VISIBILITY_MODES = ("direct", "gpu-frustum", "gpu-occlusion")
-REPEATS = (1, 2, 3)
-WARMUP_FRAMES = 10
-MEASURED_FRAMES = 30
-WIDTH, HEIGHT = 1920, 1080
-REQUIRED_COLUMNS = (
-    "light_count", "shadows", "visibility", "frame", "device", "driver",
-    "commit", "gpu_main_raster_ms", "gpu_ms", "gpu_shadow_ms", "cpu_ms",
-    "readback_cpu_ms", "validation_errors", "run_index", "effective_visibility",
-    "lighting_path", "submitted_local_lights", "omitted_local_lights",
-    "shadow_tiles", "draw_calls", "gpu_bytes", "validation_enabled", "width", "height",
-)
-TIMING_COLUMNS = ("gpu_main_raster_ms", "gpu_ms", "gpu_shadow_ms", "cpu_ms",
-                  "readback_cpu_ms")
-
-
-def build_runs(shadows: str = "both") -> list[dict]:
-    if shadows not in ("off", "on", "both"):
-        raise ValueError(f"Unsupported shadow setting: {shadows}")
-    settings = ("off", "on") if shadows == "both" else (shadows,)
-    return [{"shadows": shadow, "visibility": mode, "light_count": lights,
-             "repeat": repeat}
-            for shadow in settings for mode in VISIBILITY_MODES
-            for lights in LIGHT_COUNTS for repeat in REPEATS]
-
-
-def median(values: list[float]) -> float:
-    if not values:
-        raise ValueError("Cannot summarize empty measurements")
-    return float(statistics.median(values))
-
-
-def p95(values: list[float]) -> float:
-    if not values:
-        raise ValueError("Cannot summarize empty measurements")
-    ordered = sorted(values)
-    return ordered[math.ceil(.95 * len(ordered)) - 1]
-
-
-def _measurement(row: dict, name: str) -> float:
-    try:
-        value = float(row[name])
-    except (KeyError, TypeError, ValueError) as error:
-        raise ValueError(f"Invalid {name} in benchmark CSV") from error
-    if not math.isfinite(value) or value < 0:
-        raise ValueError(f"Invalid {name} in benchmark CSV: {value}")
-    return value
-
-
-def summarize_rows(rows: list[dict]) -> dict:
-    """Use the median of each independent run's median, then compare like baselines."""
-    grouped: dict[tuple[str, str, int], dict[int, list[dict]]] = {}
-    for row in rows:
-        try:
-            key = (row["shadows"], row["visibility"], int(row["light_count"]))
-            repeat = int(row["run_index"])
-        except (KeyError, TypeError, ValueError) as error:
-            raise ValueError("Benchmark row lacks shadow/mode/light/repeat identity") from error
-        if key[0] not in ("off", "on") or key[1] not in VISIBILITY_MODES or repeat < 1:
-            raise ValueError(f"Invalid benchmark configuration: {key}, repeat {repeat}")
-        for name in TIMING_COLUMNS:
-            _measurement(row, name)
-        grouped.setdefault(key, {}).setdefault(repeat, []).append(row)
-
-    configurations = []
-    lookup = {}
-    for (shadows, visibility, lights), repeats in sorted(grouped.items()):
-        run_summaries = []
-        for repeat, samples in sorted(repeats.items()):
-            run_summaries.append({
-                "run_index": repeat, "frames": len(samples),
-                "median_ms": {name: median([_measurement(row, name) for row in samples])
-                              for name in TIMING_COLUMNS},
-            })
-        entry = {
-            "shadows": shadows, "visibility": visibility, "light_count": lights,
-            "runs": run_summaries,
-            "median_ms": {name: median([run["median_ms"][name] for run in run_summaries])
-                          for name in TIMING_COLUMNS},
-            "p95_ms": {name: p95([_measurement(row, name) for samples in repeats.values()
-                                   for row in samples]) for name in TIMING_COLUMNS},
-        }
-        configurations.append(entry)
-        lookup[(shadows, visibility, lights)] = entry
-
-    candidates = []
-    evaluated = []
-    for entry in configurations:
-        if entry["light_count"] not in (32, 64, 128):
-            continue
-        baseline = lookup.get((entry["shadows"], entry["visibility"], 0))
-        if baseline is None:
-            raise ValueError("Forward+ gate requires a zero-light baseline for each mode/shadow setting")
-        zero_gpu = baseline["median_ms"]["gpu_ms"]
-        if zero_gpu <= 0:
-            raise ValueError("Forward+ gate requires positive zero-light GPU frame timing")
-        overhead = (entry["median_ms"]["gpu_main_raster_ms"] -
-                    baseline["median_ms"]["gpu_main_raster_ms"])
-        result = {"shadows": entry["shadows"], "visibility": entry["visibility"],
-                  "light_count": entry["light_count"], "overhead_ms": overhead,
-                  "zero_light_gpu_ms": zero_gpu,
-                  "overhead_percent_of_zero_gpu": 100 * overhead / zero_gpu,
-                  "absolute_threshold_reached": overhead >= 1.0,
-                  "relative_threshold_reached": overhead >= .15 * zero_gpu}
-        evaluated.append(result)
-        if result["absolute_threshold_reached"] or result["relative_threshold_reached"]:
-            candidates.append(result)
-    return {"configurations": configurations,
-            "forward_plus_gate": {"triggered": bool(candidates), "candidates": candidates,
-                                  "evaluated": evaluated,
-                                  "basis": "median of three independent run medians; same-mode/shadow zero-light GPU baseline"}}
-
-
-def _read_run_csv(path: Path, run: dict, commit: str) -> tuple[list[str], list[dict]]:
-    with path.open(newline="", encoding="utf-8") as stream:
-        reader = csv.DictReader(stream)
-        columns = reader.fieldnames or []
-        missing = sorted(set(REQUIRED_COLUMNS) - set(columns))
-        if missing:
-            raise ValueError(f"{path}: missing CSV column(s): {', '.join(missing)}")
-        rows = list(reader)
-    if len(rows) != MEASURED_FRAMES:
-        raise ValueError(f"{path}: expected {MEASURED_FRAMES} measured frames, got {len(rows)}")
-    frames = set()
-    for row in rows:
-        expected = {"light_count": str(run["light_count"]), "shadows": run["shadows"],
-                    "visibility": run["visibility"], "run_index": str(run["repeat"]),
-                    "commit": commit, "width": str(WIDTH), "height": str(HEIGHT)}
-        for name, value in expected.items():
-            if row[name] != value:
-                raise ValueError(f"{path}: {name} mismatch: expected {value}, got {row[name]}")
-        if row["effective_visibility"] != run["visibility"]:
-            raise ValueError(f"{path}: effective_visibility fell back from {run['visibility']}")
-        if row["submitted_local_lights"] != str(run["light_count"]) or row["omitted_local_lights"] != "0":
-            raise ValueError(f"{path}: submitted_local_lights or omitted_local_lights disagrees with the workload")
-        try:
-            frame = int(row["frame"])
-            errors = int(row["validation_errors"])
-        except ValueError as error:
-            raise ValueError(f"{path}: invalid frame or validation error count") from error
-        if frame in frames or errors != 0:
-            raise ValueError(f"{path}: duplicate frame or Vulkan validation error")
-        frames.add(frame)
-        if not row["device"] or not row["driver"] or not row["lighting_path"]:
-            raise ValueError(f"{path}: device, driver and effective lighting path are required")
-        for name in TIMING_COLUMNS:
-            _measurement(row, name)
-    return columns, rows
-
-
-def _git_revision() -> str:
-    root = Path(__file__).resolve().parents[1]
-    return subprocess.check_output(["git", "-C", str(root), "rev-parse", "HEAD"],
-                                   text=True).strip()
-
-
-def sweep(executable: Path, output: Path, shadows: str, commit: str,
-          validation: str = "off", driver: str | None = None) -> dict:
-    if not executable.is_file():
-        raise ValueError(f"Benchmark executable does not exist: {executable}")
-    if driver is None or not driver.strip() or driver.strip().lower() == "unknown":
-        raise ValueError("A measured sweep requires an explicit --driver identity")
-    if output.exists() and any(output.iterdir()):
-        raise ValueError(f"Output directory must be new or empty: {output}")
-    raw = output / "raw"
-    raw.mkdir(parents=True)
-    all_rows = []
-    columns = None
-    runs = build_runs(shadows)
-    command_prefix = [sys.executable, str(executable)] if executable.suffix.lower() == ".py" else [str(executable)]
-    for run in runs:
-        filename = (f"shadows-{run['shadows']}_{run['visibility']}_"
-                    f"lights-{run['light_count']:03d}_run-{run['repeat']}.csv")
-        target = raw / filename
-        command = command_prefix + [
-            "--lights", str(run["light_count"]), "--shadows", run["shadows"],
-            "--visibility", run["visibility"], "--csv", str(target),
-            "--run-index", str(run["repeat"]), "--commit", commit,
-            "--validation", validation, "--width", str(WIDTH), "--height", str(HEIGHT),
-            "--warmup", str(WARMUP_FRAMES), "--frames", str(MEASURED_FRAMES),
-        ]
-        if driver is not None:
-            command += ["--driver", driver]
-        result = subprocess.run(command, capture_output=True, text=True, encoding="utf-8",
-                                errors="replace", timeout=180)
-        if result.returncode != 0:
-            raise RuntimeError(f"Benchmark failed for {filename}: {result.stderr[-2000:]}")
-        run_columns, samples = _read_run_csv(target, run, commit)
-        if columns is None:
-            columns = run_columns
-        elif columns != run_columns:
-            raise ValueError(f"{target}: CSV schema differs from other runs")
-        all_rows.extend({**row, "source_csv": filename} for row in samples)
-
-    merged = output / "merged.csv"
-    with merged.open("w", newline="", encoding="utf-8") as stream:
-        writer = csv.DictWriter(stream, fieldnames=[*(columns or []), "source_csv"])
-        writer.writeheader()
-        writer.writerows(all_rows)
-    summary = {"format": "faset.p3-lighting-benchmark", "version": 1,
-               "commit": commit, "warmup_frames_per_run": WARMUP_FRAMES,
-               "measured_frames_per_run": MEASURED_FRAMES, "width": WIDTH, "height": HEIGHT,
-               "validation": validation, "driver": driver,
-               "runs_completed": len(runs), "rows": len(all_rows),
-               **summarize_rows(all_rows)}
-    (output / "summary.json").write_text(json.dumps(summary, indent=2) + "\n",
-                                          encoding="utf-8")
-    return summary
-
-
-def main() -> int:
-    parser = argparse.ArgumentParser(description=__doc__)
-    mode = parser.add_mutually_exclusive_group(required=True)
-    mode.add_argument("--list-runs", action="store_true", help="Print the deterministic sweep matrix as JSON")
-    mode.add_argument("--sweep", action="store_true", help="Run every configuration and retain raw CSV")
-    parser.add_argument("--shadows", choices=("off", "on", "both"), default="both")
-    parser.add_argument("--executable", type=Path, help="Built C++ benchmark executable")
-    parser.add_argument("--output", type=Path, help="New or empty evidence directory")
-    parser.add_argument("--commit", help="Source revision; defaults to this checkout's HEAD")
-    parser.add_argument("--driver", help="Required driver identity for a measured sweep")
-    parser.add_argument("--validation", choices=("on", "off"), default="off")
-    args = parser.parse_args()
-    if args.list_runs:
-        print(json.dumps({"format": "faset.p3-lighting-run-matrix", "version": 1,
-                          "runs": build_runs(args.shadows)}, indent=2))
-        return 0
-    if args.executable is None or args.output is None:
-        parser.error("--sweep requires --executable and --output")
-    try:
-        summary = sweep(args.executable.resolve(), args.output.resolve(), args.shadows,
-                        args.commit or _git_revision(), args.validation, args.driver)
-    except (OSError, ValueError, RuntimeError) as error:
-        print(f"P3 lighting benchmark failed: {error}", file=sys.stderr)
-        return 1
-    print(json.dumps({"summary": str(args.output.resolve() / "summary.json"),
-                      "runs_completed": summary["runs_completed"],
-                      "forward_plus_threshold_reached": summary["forward_plus_gate"]["triggered"]}))
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())