Websockets

.gitea/workflows/ci.yml

@@ -7,6 +7,9 @@ on:
       - master
       - develop
   pull_request:
+  schedule:
+    # Nightly build at 14:00 UTC, roughly midnight in Australia/Sydney.
+    - cron: "0 14 * * *"
   workflow_dispatch:
 
 jobs:
@@ -82,6 +85,7 @@ jobs:
   package-windows:
     name: Windows Release Package
     runs-on: windows-2022
+    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
     needs:
       - native-windows
       - ui-ubuntu

.vscode/launch.json

@@ -83,6 +83,23 @@
         "moduleLoad": true
       },
       "preLaunchTask": "Build DeckLinkRenderCadenceProbe Debug x64"
+    },
+    {
+      "name": "Debug RenderCadenceCompositor",
+      "type": "cppvsdbg",
+      "request": "launch",
+      "program": "${workspaceFolder}\\build\\vs2022-x64-debug\\Debug\\RenderCadenceCompositor.exe",
+      "args": [],
+      "stopAtEntry": false,
+      "cwd": "${workspaceFolder}\\build\\vs2022-x64-debug\\Debug",
+      "environment": [],
+      "console": "externalTerminal",
+      "symbolSearchPath": "${workspaceFolder}\\build\\vs2022-x64-debug\\Debug",
+      "requireExactSource": true,
+      "logging": {
+        "moduleLoad": true
+      },
+      "preLaunchTask": "Build RenderCadenceCompositor Debug x64"
     }
   ]
 }

.vscode/tasks.json

@@ -52,6 +52,22 @@
       "group": "build",
       "problemMatcher": "$msCompile"
     },
+    {
+      "label": "Build RenderCadenceCompositor Debug x64",
+      "type": "process",
+      "command": "C:\\Program Files\\Microsoft Visual Studio\\2022\\Community\\Common7\\IDE\\CommonExtensions\\Microsoft\\CMake\\CMake\\bin\\cmake.exe",
+      "args": [
+        "--build",
+        "${workspaceFolder}\\build\\vs2022-x64-debug",
+        "--config",
+        "Debug",
+        "--target",
+        "RenderCadenceCompositor",
+        "--parallel"
+      ],
+      "group": "build",
+      "problemMatcher": "$msCompile"
+    },
     {
       "label": "Clean LoopThroughWithOpenGLCompositing Debug x64",
       "type": "process",

CMakeLists.txt

@@ -273,6 +273,129 @@ if(MSVC)
 	target_compile_options(DeckLinkRenderCadenceProbe PRIVATE /W3)
 endif()
 
+set(RENDER_CADENCE_APP_DIR "${CMAKE_CURRENT_SOURCE_DIR}/apps/RenderCadenceCompositor")
+
+set(RENDER_CADENCE_APP_SOURCES
+	"${APP_DIR}/videoio/decklink/DeckLinkAPI_i.c"
+	"${APP_DIR}/videoio/decklink/DeckLinkDisplayMode.cpp"
+	"${APP_DIR}/videoio/decklink/DeckLinkDisplayMode.h"
+	"${APP_DIR}/videoio/decklink/DeckLinkFrameTransfer.cpp"
+	"${APP_DIR}/videoio/decklink/DeckLinkFrameTransfer.h"
+	"${APP_DIR}/videoio/decklink/DeckLinkSession.cpp"
+	"${APP_DIR}/videoio/decklink/DeckLinkSession.h"
+	"${APP_DIR}/videoio/decklink/DeckLinkVideoIOFormat.cpp"
+	"${APP_DIR}/videoio/decklink/DeckLinkVideoIOFormat.h"
+	"${APP_DIR}/gl/renderer/GLExtensions.cpp"
+	"${APP_DIR}/gl/renderer/GLExtensions.h"
+	"${APP_DIR}/gl/shader/Std140Buffer.h"
+	"${APP_DIR}/runtime/support/RuntimeJson.cpp"
+	"${APP_DIR}/runtime/support/RuntimeJson.h"
+	"${APP_DIR}/shader/ShaderCompiler.cpp"
+	"${APP_DIR}/shader/ShaderCompiler.h"
+	"${APP_DIR}/shader/ShaderPackageRegistry.cpp"
+	"${APP_DIR}/shader/ShaderPackageRegistry.h"
+	"${APP_DIR}/shader/ShaderTypes.h"
+	"${APP_DIR}/videoio/VideoIOFormat.cpp"
+	"${APP_DIR}/videoio/VideoIOFormat.h"
+	"${APP_DIR}/videoio/VideoIOTypes.h"
+	"${APP_DIR}/videoio/VideoPlayoutPolicy.h"
+	"${APP_DIR}/videoio/VideoPlayoutScheduler.cpp"
+	"${APP_DIR}/videoio/VideoPlayoutScheduler.h"
+	"${RENDER_CADENCE_APP_DIR}/RenderCadenceCompositor.cpp"
+	"${RENDER_CADENCE_APP_DIR}/app/AppConfig.cpp"
+	"${RENDER_CADENCE_APP_DIR}/app/AppConfig.h"
+	"${RENDER_CADENCE_APP_DIR}/app/AppConfigProvider.cpp"
+	"${RENDER_CADENCE_APP_DIR}/app/AppConfigProvider.h"
+	"${RENDER_CADENCE_APP_DIR}/app/RenderCadenceApp.h"
+	"${RENDER_CADENCE_APP_DIR}/app/RuntimeLayerController.cpp"
+	"${RENDER_CADENCE_APP_DIR}/app/RuntimeLayerController.h"
+	"${RENDER_CADENCE_APP_DIR}/control/ControlActionResult.h"
+	"${RENDER_CADENCE_APP_DIR}/control/HttpControlServer.cpp"
+	"${RENDER_CADENCE_APP_DIR}/control/HttpControlServer.h"
+	"${RENDER_CADENCE_APP_DIR}/control/RuntimeStateJson.h"
+	"${RENDER_CADENCE_APP_DIR}/frames/SystemFrameExchange.cpp"
+	"${RENDER_CADENCE_APP_DIR}/frames/SystemFrameExchange.h"
+	"${RENDER_CADENCE_APP_DIR}/frames/SystemFrameTypes.h"
+	"${RENDER_CADENCE_APP_DIR}/json/JsonWriter.cpp"
+	"${RENDER_CADENCE_APP_DIR}/json/JsonWriter.h"
+	"${RENDER_CADENCE_APP_DIR}/logging/Logger.cpp"
+	"${RENDER_CADENCE_APP_DIR}/logging/Logger.h"
+	"${RENDER_CADENCE_APP_DIR}/platform/HiddenGlWindow.cpp"
+	"${RENDER_CADENCE_APP_DIR}/platform/HiddenGlWindow.h"
+	"${RENDER_CADENCE_APP_DIR}/render/Bgra8ReadbackPipeline.cpp"
+	"${RENDER_CADENCE_APP_DIR}/render/Bgra8ReadbackPipeline.h"
+	"${RENDER_CADENCE_APP_DIR}/render/PboReadbackRing.cpp"
+	"${RENDER_CADENCE_APP_DIR}/render/PboReadbackRing.h"
+	"${RENDER_CADENCE_APP_DIR}/render/RenderCadenceClock.cpp"
+	"${RENDER_CADENCE_APP_DIR}/render/RenderCadenceClock.h"
+	"${RENDER_CADENCE_APP_DIR}/render/RenderThread.cpp"
+	"${RENDER_CADENCE_APP_DIR}/render/RenderThread.h"
+	"${RENDER_CADENCE_APP_DIR}/render/RuntimeShaderRenderer.cpp"
+	"${RENDER_CADENCE_APP_DIR}/render/RuntimeShaderRenderer.h"
+	"${RENDER_CADENCE_APP_DIR}/render/RuntimeShaderParams.cpp"
+	"${RENDER_CADENCE_APP_DIR}/render/RuntimeShaderParams.h"
+	"${RENDER_CADENCE_APP_DIR}/render/RuntimeRenderScene.cpp"
+	"${RENDER_CADENCE_APP_DIR}/render/RuntimeRenderScene.h"
+	"${RENDER_CADENCE_APP_DIR}/render/RuntimeShaderPrepareWorker.cpp"
+	"${RENDER_CADENCE_APP_DIR}/render/RuntimeShaderPrepareWorker.h"
+	"${RENDER_CADENCE_APP_DIR}/render/RuntimeShaderProgram.h"
+	"${RENDER_CADENCE_APP_DIR}/render/SimpleMotionRenderer.cpp"
+	"${RENDER_CADENCE_APP_DIR}/render/SimpleMotionRenderer.h"
+	"${RENDER_CADENCE_APP_DIR}/runtime/RuntimeLayerModel.cpp"
+	"${RENDER_CADENCE_APP_DIR}/runtime/RuntimeLayerModel.h"
+	"${RENDER_CADENCE_APP_DIR}/runtime/RuntimeShaderBridge.cpp"
+	"${RENDER_CADENCE_APP_DIR}/runtime/RuntimeShaderBridge.h"
+	"${RENDER_CADENCE_APP_DIR}/runtime/RuntimeSlangShaderCompiler.cpp"
+	"${RENDER_CADENCE_APP_DIR}/runtime/RuntimeSlangShaderCompiler.h"
+	"${RENDER_CADENCE_APP_DIR}/runtime/SupportedShaderCatalog.cpp"
+	"${RENDER_CADENCE_APP_DIR}/runtime/SupportedShaderCatalog.h"
+	"${RENDER_CADENCE_APP_DIR}/telemetry/CadenceTelemetryJson.h"
+	"${RENDER_CADENCE_APP_DIR}/telemetry/CadenceTelemetry.h"
+	"${RENDER_CADENCE_APP_DIR}/telemetry/TelemetryHealthMonitor.h"
+	"${RENDER_CADENCE_APP_DIR}/video/DeckLinkOutput.cpp"
+	"${RENDER_CADENCE_APP_DIR}/video/DeckLinkOutput.h"
+	"${RENDER_CADENCE_APP_DIR}/video/DeckLinkOutputThread.h"
+)
+
+add_executable(RenderCadenceCompositor ${RENDER_CADENCE_APP_SOURCES})
+
+target_include_directories(RenderCadenceCompositor PRIVATE
+	"${APP_DIR}"
+	"${APP_DIR}/gl/renderer"
+	"${APP_DIR}/gl/shader"
+	"${APP_DIR}/platform"
+	"${APP_DIR}/runtime/support"
+	"${APP_DIR}/shader"
+	"${APP_DIR}/videoio"
+	"${APP_DIR}/videoio/decklink"
+	"${RENDER_CADENCE_APP_DIR}"
+	"${RENDER_CADENCE_APP_DIR}/app"
+	"${RENDER_CADENCE_APP_DIR}/control"
+	"${RENDER_CADENCE_APP_DIR}/frames"
+	"${RENDER_CADENCE_APP_DIR}/json"
+	"${RENDER_CADENCE_APP_DIR}/logging"
+	"${RENDER_CADENCE_APP_DIR}/platform"
+	"${RENDER_CADENCE_APP_DIR}/render"
+	"${RENDER_CADENCE_APP_DIR}/runtime"
+	"${RENDER_CADENCE_APP_DIR}/telemetry"
+	"${RENDER_CADENCE_APP_DIR}/video"
+)
+
+target_link_libraries(RenderCadenceCompositor PRIVATE
+	opengl32
+	Ole32
+	Ws2_32
+)
+
+target_compile_definitions(RenderCadenceCompositor PRIVATE
+	_UNICODE
+	UNICODE
+)
+
+if(MSVC)
+	target_compile_options(RenderCadenceCompositor PRIVATE /W3)
+endif()
+
 add_executable(RuntimeJsonTests
 	"${APP_DIR}/runtime/support/RuntimeJson.cpp"
 	"${CMAKE_CURRENT_SOURCE_DIR}/tests/RuntimeJsonTests.cpp"
@@ -642,6 +765,227 @@ endif()
 
 add_test(NAME RenderCadenceControllerTests COMMAND RenderCadenceControllerTests)
 
+add_executable(RenderCadenceCompositorFrameExchangeTests
+	"${APP_DIR}/videoio/VideoIOFormat.cpp"
+	"${RENDER_CADENCE_APP_DIR}/frames/SystemFrameExchange.cpp"
+	"${CMAKE_CURRENT_SOURCE_DIR}/tests/RenderCadenceCompositorFrameExchangeTests.cpp"
+)
+
+target_include_directories(RenderCadenceCompositorFrameExchangeTests PRIVATE
+	"${APP_DIR}/videoio"
+	"${RENDER_CADENCE_APP_DIR}/frames"
+)
+
+if(MSVC)
+	target_compile_options(RenderCadenceCompositorFrameExchangeTests PRIVATE /W3)
+endif()
+
+add_test(NAME RenderCadenceCompositorFrameExchangeTests COMMAND RenderCadenceCompositorFrameExchangeTests)
+
+add_executable(RenderCadenceCompositorClockTests
+	"${RENDER_CADENCE_APP_DIR}/render/RenderCadenceClock.cpp"
+	"${CMAKE_CURRENT_SOURCE_DIR}/tests/RenderCadenceCompositorClockTests.cpp"
+)
+
+target_include_directories(RenderCadenceCompositorClockTests PRIVATE
+	"${RENDER_CADENCE_APP_DIR}/render"
+)
+
+if(MSVC)
+	target_compile_options(RenderCadenceCompositorClockTests PRIVATE /W3)
+endif()
+
+add_test(NAME RenderCadenceCompositorClockTests COMMAND RenderCadenceCompositorClockTests)
+
+add_executable(RenderCadenceCompositorTelemetryTests
+	"${RENDER_CADENCE_APP_DIR}/json/JsonWriter.cpp"
+	"${CMAKE_CURRENT_SOURCE_DIR}/tests/RenderCadenceCompositorTelemetryTests.cpp"
+)
+
+target_include_directories(RenderCadenceCompositorTelemetryTests PRIVATE
+	"${RENDER_CADENCE_APP_DIR}/json"
+	"${RENDER_CADENCE_APP_DIR}/telemetry"
+)
+
+if(MSVC)
+	target_compile_options(RenderCadenceCompositorTelemetryTests PRIVATE /W3)
+endif()
+
+add_test(NAME RenderCadenceCompositorTelemetryTests COMMAND RenderCadenceCompositorTelemetryTests)
+
+add_executable(RenderCadenceCompositorRuntimeShaderParamsTests
+	"${RENDER_CADENCE_APP_DIR}/render/RuntimeShaderParams.cpp"
+	"${CMAKE_CURRENT_SOURCE_DIR}/tests/RenderCadenceCompositorRuntimeShaderParamsTests.cpp"
+)
+
+target_include_directories(RenderCadenceCompositorRuntimeShaderParamsTests PRIVATE
+	"${APP_DIR}/gl/shader"
+	"${APP_DIR}/shader"
+	"${RENDER_CADENCE_APP_DIR}/render"
+	"${RENDER_CADENCE_APP_DIR}/runtime"
+)
+
+if(MSVC)
+	target_compile_options(RenderCadenceCompositorRuntimeShaderParamsTests PRIVATE /W3)
+endif()
+
+add_test(NAME RenderCadenceCompositorRuntimeShaderParamsTests COMMAND RenderCadenceCompositorRuntimeShaderParamsTests)
+
+add_executable(RenderCadenceCompositorRuntimeLayerModelTests
+	"${RENDER_CADENCE_APP_DIR}/runtime/RuntimeLayerModel.cpp"
+	"${RENDER_CADENCE_APP_DIR}/runtime/SupportedShaderCatalog.cpp"
+	"${APP_DIR}/shader/ShaderPackageRegistry.cpp"
+	"${APP_DIR}/runtime/support/RuntimeJson.cpp"
+	"${CMAKE_CURRENT_SOURCE_DIR}/tests/RenderCadenceCompositorRuntimeLayerModelTests.cpp"
+)
+
+target_include_directories(RenderCadenceCompositorRuntimeLayerModelTests PRIVATE
+	"${APP_DIR}"
+	"${APP_DIR}/runtime/support"
+	"${APP_DIR}/shader"
+	"${RENDER_CADENCE_APP_DIR}/runtime"
+)
+
+if(MSVC)
+	target_compile_options(RenderCadenceCompositorRuntimeLayerModelTests PRIVATE /W3)
+endif()
+
+add_test(NAME RenderCadenceCompositorRuntimeLayerModelTests COMMAND RenderCadenceCompositorRuntimeLayerModelTests)
+
+add_executable(RenderCadenceCompositorSupportedShaderCatalogTests
+	"${APP_DIR}/shader/ShaderPackageRegistry.cpp"
+	"${APP_DIR}/runtime/support/RuntimeJson.cpp"
+	"${RENDER_CADENCE_APP_DIR}/runtime/SupportedShaderCatalog.cpp"
+	"${CMAKE_CURRENT_SOURCE_DIR}/tests/RenderCadenceCompositorSupportedShaderCatalogTests.cpp"
+)
+
+target_include_directories(RenderCadenceCompositorSupportedShaderCatalogTests PRIVATE
+	"${APP_DIR}"
+	"${APP_DIR}/runtime/support"
+	"${APP_DIR}/shader"
+	"${RENDER_CADENCE_APP_DIR}/runtime"
+)
+
+if(MSVC)
+	target_compile_options(RenderCadenceCompositorSupportedShaderCatalogTests PRIVATE /W3)
+endif()
+
+add_test(NAME RenderCadenceCompositorSupportedShaderCatalogTests COMMAND RenderCadenceCompositorSupportedShaderCatalogTests)
+
+add_executable(RenderCadenceCompositorLoggerTests
+	"${RENDER_CADENCE_APP_DIR}/logging/Logger.cpp"
+	"${CMAKE_CURRENT_SOURCE_DIR}/tests/RenderCadenceCompositorLoggerTests.cpp"
+)
+
+target_include_directories(RenderCadenceCompositorLoggerTests PRIVATE
+	"${RENDER_CADENCE_APP_DIR}/logging"
+)
+
+if(MSVC)
+	target_compile_options(RenderCadenceCompositorLoggerTests PRIVATE /W3)
+endif()
+
+add_test(NAME RenderCadenceCompositorLoggerTests COMMAND RenderCadenceCompositorLoggerTests)
+
+add_executable(RenderCadenceCompositorJsonWriterTests
+	"${RENDER_CADENCE_APP_DIR}/json/JsonWriter.cpp"
+	"${CMAKE_CURRENT_SOURCE_DIR}/tests/RenderCadenceCompositorJsonWriterTests.cpp"
+)
+
+target_include_directories(RenderCadenceCompositorJsonWriterTests PRIVATE
+	"${RENDER_CADENCE_APP_DIR}/json"
+)
+
+if(MSVC)
+	target_compile_options(RenderCadenceCompositorJsonWriterTests PRIVATE /W3)
+endif()
+
+add_test(NAME RenderCadenceCompositorJsonWriterTests COMMAND RenderCadenceCompositorJsonWriterTests)
+
+add_executable(RenderCadenceCompositorRuntimeStateJsonTests
+	"${APP_DIR}/runtime/support/RuntimeJson.cpp"
+	"${APP_DIR}/shader/ShaderPackageRegistry.cpp"
+	"${RENDER_CADENCE_APP_DIR}/app/AppConfig.cpp"
+	"${RENDER_CADENCE_APP_DIR}/app/AppConfigProvider.cpp"
+	"${RENDER_CADENCE_APP_DIR}/json/JsonWriter.cpp"
+	"${RENDER_CADENCE_APP_DIR}/runtime/RuntimeLayerModel.cpp"
+	"${RENDER_CADENCE_APP_DIR}/runtime/SupportedShaderCatalog.cpp"
+	"${CMAKE_CURRENT_SOURCE_DIR}/tests/RenderCadenceCompositorRuntimeStateJsonTests.cpp"
+)
+
+target_include_directories(RenderCadenceCompositorRuntimeStateJsonTests PRIVATE
+	"${APP_DIR}"
+	"${APP_DIR}/runtime/support"
+	"${APP_DIR}/shader"
+	"${APP_DIR}/videoio"
+	"${APP_DIR}/videoio/decklink"
+	"${RENDER_CADENCE_APP_DIR}/app"
+	"${RENDER_CADENCE_APP_DIR}/control"
+	"${RENDER_CADENCE_APP_DIR}/json"
+	"${RENDER_CADENCE_APP_DIR}/logging"
+	"${RENDER_CADENCE_APP_DIR}/runtime"
+	"${RENDER_CADENCE_APP_DIR}/telemetry"
+	"${RENDER_CADENCE_APP_DIR}/video"
+)
+
+if(MSVC)
+	target_compile_options(RenderCadenceCompositorRuntimeStateJsonTests PRIVATE /W3)
+endif()
+
+add_test(NAME RenderCadenceCompositorRuntimeStateJsonTests COMMAND RenderCadenceCompositorRuntimeStateJsonTests)
+
+add_executable(RenderCadenceCompositorHttpControlServerTests
+	"${RENDER_CADENCE_APP_DIR}/control/HttpControlServer.cpp"
+	"${RENDER_CADENCE_APP_DIR}/json/JsonWriter.cpp"
+	"${RENDER_CADENCE_APP_DIR}/logging/Logger.cpp"
+	"${CMAKE_CURRENT_SOURCE_DIR}/tests/RenderCadenceCompositorHttpControlServerTests.cpp"
+)
+
+target_include_directories(RenderCadenceCompositorHttpControlServerTests PRIVATE
+	"${RENDER_CADENCE_APP_DIR}/control"
+	"${RENDER_CADENCE_APP_DIR}/json"
+	"${RENDER_CADENCE_APP_DIR}/logging"
+)
+
+target_link_libraries(RenderCadenceCompositorHttpControlServerTests PRIVATE
+	Ws2_32
+)
+
+if(MSVC)
+	target_compile_options(RenderCadenceCompositorHttpControlServerTests PRIVATE /W3)
+endif()
+
+add_test(NAME RenderCadenceCompositorHttpControlServerTests COMMAND RenderCadenceCompositorHttpControlServerTests)
+
+add_executable(RenderCadenceCompositorAppConfigProviderTests
+	"${APP_DIR}/runtime/support/RuntimeJson.cpp"
+	"${RENDER_CADENCE_APP_DIR}/app/AppConfig.cpp"
+	"${RENDER_CADENCE_APP_DIR}/app/AppConfigProvider.cpp"
+	"${CMAKE_CURRENT_SOURCE_DIR}/tests/RenderCadenceCompositorAppConfigProviderTests.cpp"
+)
+
+target_include_directories(RenderCadenceCompositorAppConfigProviderTests PRIVATE
+	"${APP_DIR}"
+	"${APP_DIR}/runtime/support"
+	"${RENDER_CADENCE_APP_DIR}/app"
+	"${RENDER_CADENCE_APP_DIR}/control"
+	"${RENDER_CADENCE_APP_DIR}/logging"
+	"${RENDER_CADENCE_APP_DIR}/telemetry"
+	"${RENDER_CADENCE_APP_DIR}/video"
+	"${APP_DIR}/videoio"
+	"${APP_DIR}/videoio/decklink"
+)
+
+target_link_libraries(RenderCadenceCompositorAppConfigProviderTests PRIVATE
+	Ws2_32
+)
+
+if(MSVC)
+	target_compile_options(RenderCadenceCompositorAppConfigProviderTests PRIVATE /W3)
+endif()
+
+add_test(NAME RenderCadenceCompositorAppConfigProviderTests COMMAND RenderCadenceCompositorAppConfigProviderTests)
+
 add_executable(SystemOutputFramePoolTests
 	"${APP_DIR}/videoio/SystemOutputFramePool.cpp"
 	"${APP_DIR}/videoio/VideoIOFormat.cpp"

apps/RenderCadenceCompositor/README.md

@@ -0,0 +1,288 @@
+# RenderCadenceCompositor
+
+This app is the modular version of the working DeckLink render-cadence probe.
+
+Its job is to prove the production-facing foundation before the current compositor's shader/runtime/control features are ported over.
+
+Before adding features here, read the guardrails in [Render Cadence Golden Rules](../../docs/RENDER_CADENCE_GOLDEN_RULES.md).
+
+## Architecture
+
+```text
+RenderThread
+  owns a hidden OpenGL context
+  renders simple BGRA8 motion at selected cadence
+  queues async PBO readback
+  publishes completed frames into SystemFrameExchange
+
+SystemFrameExchange
+  owns Free / Rendering / Completed / Scheduled slots
+  drops old completed unscheduled frames when render needs space
+  protects scheduled frames until DeckLink completion
+
+DeckLinkOutputThread
+  consumes completed system-memory frames
+  schedules them into DeckLink up to target depth
+  never renders
+```
+
+Startup warms up real rendered frames before DeckLink scheduled playback starts.
+
+## Current Scope
+
+Included now:
+
+- output-only DeckLink
+- non-blocking startup when DeckLink output is unavailable
+- hidden render-thread-owned OpenGL context
+- simple smooth-motion renderer
+- BGRA8-only output
+- async PBO readback
+- latest-N system-memory frame exchange
+- rendered-frame warmup
+- background Slang compile of `shaders/happy-accident`
+- app-owned display/render layer model for shader build readiness
+- app-owned submission of a completed shader artifact
+- render-thread-owned runtime render scene for ready shader layers
+- shared-context GL prepare worker for runtime shader program compile/link
+- render-thread-only GL program swap once a prepared program is ready
+- manifest-driven stateless single-pass shader packages
+- HTTP shader list populated from supported stateless single-pass shader packages
+- default float, vec2, color, boolean, enum, and trigger parameters
+- small JSON writer for future HTTP/WebSocket payloads
+- JSON serialization for cadence telemetry snapshots
+- background logging with `log`, `warning`, and `error` levels
+- local HTTP control server matching the OpenAPI route surface
+- startup config provider for `config/runtime-host.json`
+- quiet telemetry health monitor
+- non-GL frame-exchange tests
+
+Intentionally not included yet:
+
+- DeckLink input
+- multipass shader rendering
+- temporal/history/feedback shader storage
+- texture/LUT asset upload
+- text-parameter rasterization
+- runtime state
+- OSC/API control
+- preview
+- screenshots
+- persistence
+
+Those features should be ported only after the cadence spine is stable.
+
+## Build
+
+```powershell
+cmake --build --preset build-debug --target RenderCadenceCompositor -- /m:1
+```
+
+The executable is:
+
+```text
+build\vs2022-x64-debug\Debug\RenderCadenceCompositor.exe
+```
+
+## Run
+
+Run from VS Code with:
+
+```text
+Debug RenderCadenceCompositor
+```
+
+Or from a terminal:
+
+```powershell
+build\vs2022-x64-debug\Debug\RenderCadenceCompositor.exe
+```
+
+Press Enter to stop.
+
+To test a different compatible shader package:
+
+```powershell
+build\vs2022-x64-debug\Debug\RenderCadenceCompositor.exe --shader solid-color
+```
+
+Use `--no-shader` to keep the simple motion fallback only.
+
+## Startup Config
+
+On startup the app loads `config/runtime-host.json` through `AppConfigProvider`, then applies explicit CLI overrides.
+
+Currently consumed fields:
+
+- `serverPort`
+- `shaderLibrary`
+- `oscBindAddress`
+- `oscPort`
+- `oscSmoothing`
+- `inputVideoFormat`
+- `inputFrameRate`
+- `outputVideoFormat`
+- `outputFrameRate`
+- `autoReload`
+- `maxTemporalHistoryFrames`
+- `previewFps`
+- `enableExternalKeying`
+
+The loaded config is treated as a read-only startup snapshot. Subsystems that need config should receive this snapshot or a narrowed config struct from app orchestration; they should not reload files independently.
+
+Supported CLI overrides:
+
+- `--shader <shader-id>`
+- `--no-shader`
+- `--port <port>`
+
+## Expected Telemetry
+
+Startup, shutdown, shader-build, and render-thread event messages are written through the app logger. Telemetry is intentionally separate and remains a compact once-per-second cadence line.
+
+The logger writes to the console, `OutputDebugStringA`, and `logs/render-cadence-compositor.log` by default. Render-thread log calls use the non-blocking path so diagnostics do not become cadence blockers.
+
+## HTTP Control Server
+
+The app starts a local HTTP control server on `http://127.0.0.1:8080` by default, searching nearby ports if that one is busy.
+
+Current endpoints:
+
+- `GET /` and UI asset paths: serve the bundled control UI from `ui/dist`
+- `GET /api/state`: returns OpenAPI-shaped display data with cadence telemetry, supported shaders, output status, and a read-only current runtime layer
+- `GET /ws`: upgrades to a WebSocket and streams state snapshots when they change
+- `GET /docs/openapi.yaml` and `GET /openapi.yaml`: serves the OpenAPI document
+- `GET /docs`: serves Swagger UI
+- `POST /api/layers/add` and `POST /api/layers/remove` mutate the app-owned display layer model only
+- other OpenAPI POST routes are present but return `{ "ok": false, "error": "Endpoint is not implemented in RenderCadenceCompositor yet." }`
+
+The HTTP server runs on its own thread. It serves static UI/docs files, samples/copies telemetry through callbacks, and does not call render work or DeckLink scheduling.
+
+## Optional DeckLink Output
+
+DeckLink output is an optional edge service in this app.
+
+Startup order is:
+
+1. start render thread
+2. warm up rendered system-memory frames
+3. try to attach DeckLink output
+4. start telemetry and HTTP either way
+
+If DeckLink discovery or output setup fails, the app logs a warning and continues running without starting the output scheduler or scheduled playback. This keeps render cadence, runtime shader testing, HTTP state, and logging available on machines without DeckLink hardware or drivers.
+
+`/api/state` reports the output status in `videoIO.statusMessage`.
+
+The app samples telemetry once per second.
+
+Normal cadence samples are available through `GET /api/state` and are not printed to the console. The telemetry monitor only logs health events:
+
+- warning when DeckLink late/dropped-frame counters increase
+- warning when schedule failures increase
+- error when the app/DeckLink output buffer is starved
+
+Healthy first-run signs:
+
+- visible DeckLink output is smooth
+- `renderFps` is close to the selected cadence
+- `scheduleFps` is close to the selected cadence after warmup
+- `scheduled` stays near 4
+- `decklinkBuffered` stays near 4 when available
+- `late` and `dropped` do not increase continuously
+- `scheduleFailures` does not increase
+- `shaderCommitted` becomes `1` after the background Happy Accident compile completes
+- `shaderFailures` remains `0`
+
+`completedPollMisses` means the DeckLink scheduling thread woke up before a completed frame was available. It is not a DeckLink playout underrun by itself. Treat it as healthy polling noise when `scheduled`, `decklinkBuffered`, `late`, `dropped`, and `scheduleFailures` remain stable.
+
+## Runtime Slang Shader Test
+
+On startup the app begins compiling the selected shader package on a background thread owned by the app orchestration layer. The default is `shaders/happy-accident`.
+
+The render thread keeps drawing the simple motion renderer while Slang compiles. It does not choose packages, launch Slang, or track build lifecycle. Once a completed shader artifact is published, the render-thread-owned runtime scene queues changed layers to a shared-context GL prepare worker. That worker compiles/links runtime shader programs off the cadence thread. The render thread only swaps in an already-prepared GL program at a frame boundary. If either the Slang build or GL preparation fails, the app keeps rendering the current renderer or simple motion fallback.
+
+Current runtime shader support is deliberately limited to stateless single-pass packages:
+
+- one pass only
+- no temporal history
+- no feedback storage
+- no texture/LUT assets yet
+- no text parameters yet
+- manifest defaults are used for parameters
+- `gVideoInput` and `gLayerInput` are bound to a small fallback source texture until DeckLink input is added
+
+The `/api/state` shader list uses the same support rules as runtime shader compilation and reports only packages this app can run today. Unsupported manifest feature sets such as multipass, temporal, feedback, texture-backed, font-backed, or text-parameter shaders are hidden from the control UI for now.
+
+Runtime shaders are exposed through `RuntimeLayerModel` as display layers with manifest parameter defaults. The model also records whether each layer has a render-ready artifact. Add/remove POST controls mutate this app-owned model and may start background shader builds.
+
+When a layer becomes render-ready, the app publishes the ready render-layer snapshot to the render thread. The render thread owns the GL-side `RuntimeRenderScene`, diffs that snapshot at a frame boundary, queues new or changed programs to the shared-context prepare worker, swaps in prepared programs when available, removes obsolete GL programs, and renders ready layers in order. Current layer rendering is still deliberately simple: each stateless full-frame shader draws to the output target using fallback source textures until proper layer-input texture handoff is designed.
+
+Successful handoff signs:
+
+- telemetry shows `shaderCommitted=1`
+- output changes from the simple motion pattern to the Happy Accident shader
+- render/schedule cadence remains near 60 fps during and after the handoff
+- DeckLink buffer remains stable
+
+## Baseline Result
+
+Date: 2026-05-12
+
+User-visible result:
+
+- output was smooth
+- DeckLink held a 4-frame buffer
+
+Representative telemetry:
+
+```text
+renderFps=59.9 scheduleFps=59.9 free=8 completed=0 scheduled=4 completedPollMisses=30 scheduleFailures=0 completions=720 late=0 dropped=0 decklinkBuffered=4 scheduleCallMs=1.2
+renderFps=59.8 scheduleFps=59.8 free=7 completed=1 scheduled=4 completedPollMisses=36 scheduleFailures=0 completions=1080 late=0 dropped=0 decklinkBuffered=4 scheduleCallMs=4.7
+renderFps=59.9 scheduleFps=59.9 free=7 completed=1 scheduled=4 completedPollMisses=86 scheduleFailures=0 completions=1381 late=0 dropped=0 decklinkBuffered=4 scheduleCallMs=2.1
+```
+
+Read:
+
+- render cadence and DeckLink schedule cadence both held roughly 60 fps
+- app scheduled depth stayed at 4
+- actual DeckLink buffered depth stayed at 4
+- no late frames, dropped frames, or schedule failures were observed
+- completed poll misses were benign because playout remained fully fed
+
+## Tests
+
+```powershell
+cmake --build --preset build-debug --target RenderCadenceCompositorFrameExchangeTests -- /m:1
+ctest --test-dir build\vs2022-x64-debug -C Debug -R RenderCadenceCompositorFrameExchangeTests --output-on-failure
+```
+
+## Relationship To The Probe
+
+`apps/DeckLinkRenderCadenceProbe` proved the timing model in one compact file.
+
+This app keeps the same core behavior but splits it into modules that can grow:
+
+- `frames/`: system-memory handoff
+- `platform/`: COM/Win32/hidden GL context support
+- `render/`: cadence, simple rendering, PBO readback
+- `render/RuntimeRenderScene`: render-thread-owned GL scene for ready runtime shader layers
+- `render/RuntimeShaderPrepareWorker`: shared-context runtime shader program compile/link worker
+- `runtime/`: app-owned shader layer readiness model, runtime Slang build bridge, and completed artifact handoff
+- `control/`: local HTTP API edge and runtime-state JSON presentation
+- `json/`: compact JSON serialization helpers
+- `video/`: DeckLink output wrapper and scheduling thread
+- `telemetry/`: cadence telemetry
+- `telemetry/TelemetryHealthMonitor`: quiet health event logging from telemetry samples
+- `app/`: startup/shutdown orchestration
+- `app/AppConfigProvider`: startup config loading and CLI overrides
+
+## Next Porting Steps
+
+Only after this app matches the probe's smooth output:
+
+1. replace `SimpleMotionRenderer` with a render-scene interface
+2. port shader package rendering
+3. port runtime snapshots/live state
+4. add control services
+5. add preview/screenshot from system-memory frames
+6. add DeckLink input as a CPU latest-frame mailbox

apps/RenderCadenceCompositor/RenderCadenceCompositor.cpp

@@ -0,0 +1,107 @@
+#include "app/AppConfig.h"
+#include "app/AppConfigProvider.h"
+#include "app/RenderCadenceApp.h"
+#include "frames/SystemFrameExchange.h"
+#include "logging/Logger.h"
+#include "render/RenderThread.h"
+#include "VideoIOFormat.h"
+
+#include <windows.h>
+
+#include <iostream>
+#include <sstream>
+#include <string>
+
+namespace
+{
+class ComInitGuard
+{
+public:
+	~ComInitGuard()
+	{
+		if (mInitialized)
+			CoUninitialize();
+	}
+
+	bool Initialize()
+	{
+		const HRESULT result = CoInitialize(nullptr);
+		mInitialized = SUCCEEDED(result);
+		mResult = result;
+		return mInitialized;
+	}
+
+	HRESULT Result() const { return mResult; }
+
+private:
+	bool mInitialized = false;
+	HRESULT mResult = S_OK;
+};
+}
+
+int main(int argc, char** argv)
+{
+	RenderCadenceCompositor::AppConfigProvider configProvider;
+	std::string configError;
+	if (!configProvider.LoadDefault(configError))
+	{
+		RenderCadenceCompositor::Logger::Instance().Start(RenderCadenceCompositor::DefaultAppConfig().logging);
+		RenderCadenceCompositor::LogError("app", "Config load failed: " + configError);
+		RenderCadenceCompositor::Logger::Instance().Stop();
+		return 1;
+	}
+	configProvider.ApplyCommandLine(argc, argv);
+
+	RenderCadenceCompositor::AppConfig appConfig = configProvider.Config();
+	RenderCadenceCompositor::Logger::Instance().Start(appConfig.logging);
+	RenderCadenceCompositor::Log(
+		"app",
+		"RenderCadenceCompositor starting. Starts render cadence, system-memory exchange, DeckLink scheduled output, and telemetry. Press Enter to stop.");
+	RenderCadenceCompositor::Log("app", "Loaded config from " + configProvider.SourcePath().string());
+
+	ComInitGuard com;
+	if (!com.Initialize())
+	{
+		std::ostringstream message;
+		message << "COM initialization failed: 0x" << std::hex << com.Result();
+		RenderCadenceCompositor::LogError("app", message.str());
+		RenderCadenceCompositor::Logger::Instance().Stop();
+		return 1;
+	}
+
+	SystemFrameExchangeConfig frameExchangeConfig;
+	RenderCadenceCompositor::VideoFormatDimensions(
+		appConfig.outputVideoFormat,
+		frameExchangeConfig.width,
+		frameExchangeConfig.height);
+	frameExchangeConfig.pixelFormat = VideoIOPixelFormat::Bgra8;
+	frameExchangeConfig.rowBytes = VideoIORowBytes(frameExchangeConfig.pixelFormat, frameExchangeConfig.width);
+	frameExchangeConfig.capacity = 12;
+
+	SystemFrameExchange frameExchange(frameExchangeConfig);
+
+	RenderThread::Config renderConfig;
+	renderConfig.width = frameExchangeConfig.width;
+	renderConfig.height = frameExchangeConfig.height;
+	renderConfig.frameDurationMilliseconds = RenderCadenceCompositor::FrameDurationMillisecondsFromRateString(appConfig.outputFrameRate);
+	renderConfig.pboDepth = 6;
+
+	RenderThread renderThread(frameExchange, renderConfig);
+
+	RenderCadenceCompositor::RenderCadenceApp<RenderThread, SystemFrameExchange> app(renderThread, frameExchange, appConfig);
+
+	std::string error;
+	if (!app.Start(error))
+	{
+		RenderCadenceCompositor::LogError("app", "RenderCadenceCompositor start failed: " + error);
+		RenderCadenceCompositor::Logger::Instance().Stop();
+		return 1;
+	}
+
+	std::string line;
+	std::getline(std::cin, line);
+	app.Stop();
+	RenderCadenceCompositor::Log("app", "RenderCadenceCompositor stopped.");
+	RenderCadenceCompositor::Logger::Instance().Stop();
+	return 0;
+}

apps/RenderCadenceCompositor/app/AppConfig.cpp

@@ -0,0 +1,39 @@
+#include "AppConfig.h"
+
+namespace RenderCadenceCompositor
+{
+AppConfig DefaultAppConfig()
+{
+	AppConfig config;
+	config.deckLink.externalKeyingEnabled = false;
+	config.deckLink.outputAlphaRequired = false;
+	config.outputThread.targetBufferedFrames = 4;
+	config.telemetry.interval = std::chrono::seconds(1);
+	config.logging.minimumLevel = LogLevel::Log;
+	config.logging.writeToConsole = true;
+	config.logging.writeToDebugOutput = true;
+	config.logging.writeToFile = true;
+	config.logging.filePath = "logs/render-cadence-compositor.log";
+	config.logging.maxQueuedMessages = 1024;
+	config.http.preferredPort = 8080;
+	config.http.portSearchCount = 20;
+	config.http.idleSleep = std::chrono::milliseconds(10);
+	config.shaderLibrary = "shaders";
+	config.oscBindAddress = "0.0.0.0";
+	config.oscPort = 9000;
+	config.oscSmoothing = 0.18;
+	config.inputVideoFormat = "1080p";
+	config.inputFrameRate = "59.94";
+	config.outputVideoFormat = "1080p";
+	config.outputFrameRate = "59.94";
+	config.autoReload = true;
+	config.maxTemporalHistoryFrames = 12;
+	config.previewFps = 30.0;
+	config.warmupCompletedFrames = 4;
+	config.warmupTimeout = std::chrono::seconds(3);
+	config.prerollTimeout = std::chrono::seconds(3);
+	config.prerollPoll = std::chrono::milliseconds(2);
+	config.runtimeShaderId = "happy-accident";
+	return config;
+}
+}

apps/RenderCadenceCompositor/app/AppConfig.h

@@ -0,0 +1,41 @@
+#pragma once
+
+#include "../control/HttpControlServer.h"
+#include "../logging/Logger.h"
+#include "../telemetry/TelemetryHealthMonitor.h"
+#include "../video/DeckLinkOutput.h"
+#include "../video/DeckLinkOutputThread.h"
+
+#include <chrono>
+#include <cstddef>
+#include <string>
+
+namespace RenderCadenceCompositor
+{
+struct AppConfig
+{
+	DeckLinkOutputConfig deckLink;
+	DeckLinkOutputThreadConfig outputThread;
+	TelemetryHealthMonitorConfig telemetry;
+	LoggerConfig logging;
+	HttpControlServerConfig http;
+	std::string shaderLibrary = "shaders";
+	std::string oscBindAddress = "0.0.0.0";
+	unsigned short oscPort = 9000;
+	double oscSmoothing = 0.18;
+	std::string inputVideoFormat = "1080p";
+	std::string inputFrameRate = "59.94";
+	std::string outputVideoFormat = "1080p";
+	std::string outputFrameRate = "59.94";
+	bool autoReload = true;
+	std::size_t maxTemporalHistoryFrames = 12;
+	double previewFps = 30.0;
+	std::size_t warmupCompletedFrames = 4;
+	std::chrono::milliseconds warmupTimeout = std::chrono::seconds(3);
+	std::chrono::milliseconds prerollTimeout = std::chrono::seconds(3);
+	std::chrono::milliseconds prerollPoll = std::chrono::milliseconds(2);
+	std::string runtimeShaderId = "happy-accident";
+};
+
+AppConfig DefaultAppConfig();
+}

apps/RenderCadenceCompositor/app/AppConfigProvider.cpp

@@ -0,0 +1,237 @@
+#include "AppConfigProvider.h"
+
+#include "RuntimeJson.h"
+
+#include <algorithm>
+#include <cctype>
+#include <cstdlib>
+#include <fstream>
+#include <sstream>
+#include <vector>
+#include <windows.h>
+
+namespace RenderCadenceCompositor
+{
+namespace
+{
+std::filesystem::path ExecutableDirectory()
+{
+	char path[MAX_PATH] = {};
+	const DWORD length = GetModuleFileNameA(nullptr, path, static_cast<DWORD>(sizeof(path)));
+	if (length == 0 || length >= sizeof(path))
+		return std::filesystem::current_path();
+	return std::filesystem::path(path).parent_path();
+}
+
+std::string ReadTextFile(const std::filesystem::path& path, std::string& error)
+{
+	std::ifstream input(path, std::ios::binary);
+	if (!input)
+	{
+		error = "Could not open config file: " + path.string();
+		return std::string();
+	}
+
+	std::ostringstream buffer;
+	buffer << input.rdbuf();
+	return buffer.str();
+}
+
+const JsonValue* Find(const JsonValue& root, const char* key)
+{
+	return root.find(key);
+}
+
+void ApplyString(const JsonValue& root, const char* key, std::string& target)
+{
+	const JsonValue* value = Find(root, key);
+	if (value && value->isString())
+		target = value->asString();
+}
+
+void ApplyBool(const JsonValue& root, const char* key, bool& target)
+{
+	const JsonValue* value = Find(root, key);
+	if (value && value->isBoolean())
+		target = value->asBoolean();
+}
+
+void ApplyDouble(const JsonValue& root, const char* key, double& target)
+{
+	const JsonValue* value = Find(root, key);
+	if (value && value->isNumber())
+		target = value->asNumber();
+}
+
+void ApplySize(const JsonValue& root, const char* key, std::size_t& target)
+{
+	const JsonValue* value = Find(root, key);
+	if (value && value->isNumber() && value->asNumber() >= 0.0)
+		target = static_cast<std::size_t>(value->asNumber());
+}
+
+void ApplyPort(const JsonValue& root, const char* key, unsigned short& target)
+{
+	const JsonValue* value = Find(root, key);
+	if (!value || !value->isNumber())
+		return;
+
+	const double port = value->asNumber();
+	if (port >= 1.0 && port <= 65535.0)
+		target = static_cast<unsigned short>(port);
+}
+}
+
+AppConfigProvider::AppConfigProvider() :
+	mConfig(DefaultAppConfig())
+{
+}
+
+bool AppConfigProvider::LoadDefault(std::string& error)
+{
+	const std::filesystem::path path = FindConfigFile();
+	if (path.empty())
+	{
+		error = "Could not locate config/runtime-host.json from current directory or executable directory.";
+		return false;
+	}
+	return Load(path, error);
+}
+
+bool AppConfigProvider::Load(const std::filesystem::path& path, std::string& error)
+{
+	mConfig = DefaultAppConfig();
+	mSourcePath = path;
+	mLoadedFromFile = false;
+
+	std::string fileError;
+	const std::string text = ReadTextFile(path, fileError);
+	if (!fileError.empty())
+	{
+		error = fileError;
+		return false;
+	}
+
+	JsonValue root;
+	std::string parseError;
+	if (!ParseJson(text, root, parseError) || !root.isObject())
+	{
+		error = parseError.empty() ? "Config root must be a JSON object." : parseError;
+		return false;
+	}
+
+	ApplyString(root, "shaderLibrary", mConfig.shaderLibrary);
+	ApplyPort(root, "serverPort", mConfig.http.preferredPort);
+	ApplyString(root, "oscBindAddress", mConfig.oscBindAddress);
+	ApplyPort(root, "oscPort", mConfig.oscPort);
+	ApplyDouble(root, "oscSmoothing", mConfig.oscSmoothing);
+	ApplyString(root, "inputVideoFormat", mConfig.inputVideoFormat);
+	ApplyString(root, "inputFrameRate", mConfig.inputFrameRate);
+	ApplyString(root, "outputVideoFormat", mConfig.outputVideoFormat);
+	ApplyString(root, "outputFrameRate", mConfig.outputFrameRate);
+	ApplyBool(root, "autoReload", mConfig.autoReload);
+	ApplySize(root, "maxTemporalHistoryFrames", mConfig.maxTemporalHistoryFrames);
+	ApplyDouble(root, "previewFps", mConfig.previewFps);
+	ApplyBool(root, "enableExternalKeying", mConfig.deckLink.externalKeyingEnabled);
+
+	mLoadedFromFile = true;
+	error.clear();
+	return true;
+}
+
+void AppConfigProvider::ApplyCommandLine(int argc, char** argv)
+{
+	for (int index = 1; index < argc; ++index)
+	{
+		const std::string argument = argv[index];
+		if (argument == "--shader" && index + 1 < argc)
+		{
+			mConfig.runtimeShaderId = argv[++index];
+			continue;
+		}
+		if (argument == "--no-shader")
+		{
+			mConfig.runtimeShaderId.clear();
+			continue;
+		}
+		if (argument == "--port" && index + 1 < argc)
+		{
+			const int port = std::atoi(argv[++index]);
+			if (port >= 1 && port <= 65535)
+				mConfig.http.preferredPort = static_cast<unsigned short>(port);
+			continue;
+		}
+	}
+}
+
+double FrameDurationMillisecondsFromRateString(const std::string& rateText, double fallbackRate)
+{
+	double rate = fallbackRate;
+	try
+	{
+		rate = std::stod(rateText);
+	}
+	catch (...)
+	{
+		rate = fallbackRate;
+	}
+
+	if (rate <= 0.0)
+		rate = fallbackRate;
+	return 1000.0 / rate;
+}
+
+void VideoFormatDimensions(const std::string& formatName, unsigned& width, unsigned& height)
+{
+	std::string normalized = formatName;
+	std::transform(normalized.begin(), normalized.end(), normalized.begin(), [](unsigned char character) {
+		return static_cast<char>(std::tolower(character));
+	});
+
+	if (normalized == "720p")
+	{
+		width = 1280;
+		height = 720;
+		return;
+	}
+
+	if (normalized == "2160p" || normalized == "4k" || normalized == "uhd")
+	{
+		width = 3840;
+		height = 2160;
+		return;
+	}
+
+	width = 1920;
+	height = 1080;
+}
+
+std::filesystem::path FindConfigFile(const std::filesystem::path& relativePath)
+{
+	return FindRepoPath(relativePath);
+}
+
+std::filesystem::path FindRepoPath(const std::filesystem::path& relativePath)
+{
+	std::vector<std::filesystem::path> starts;
+	starts.push_back(std::filesystem::current_path());
+	starts.push_back(ExecutableDirectory());
+
+	for (std::filesystem::path start : starts)
+	{
+		for (;;)
+		{
+			const std::filesystem::path candidate = start / relativePath;
+			if (std::filesystem::exists(candidate))
+				return candidate;
+
+			const std::filesystem::path parent = start.parent_path();
+			if (parent.empty() || parent == start)
+				break;
+			start = parent;
+		}
+	}
+
+	return std::filesystem::path();
+}
+}

apps/RenderCadenceCompositor/app/AppConfigProvider.h

@@ -0,0 +1,33 @@
+#pragma once
+
+#include "AppConfig.h"
+
+#include <filesystem>
+#include <string>
+
+namespace RenderCadenceCompositor
+{
+class AppConfigProvider
+{
+public:
+	AppConfigProvider();
+
+bool Load(const std::filesystem::path& path, std::string& error);
+bool LoadDefault(std::string& error);
+	void ApplyCommandLine(int argc, char** argv);
+
+	const AppConfig& Config() const { return mConfig; }
+	const std::filesystem::path& SourcePath() const { return mSourcePath; }
+	bool LoadedFromFile() const { return mLoadedFromFile; }
+
+private:
+	AppConfig mConfig;
+	std::filesystem::path mSourcePath;
+	bool mLoadedFromFile = false;
+};
+
+double FrameDurationMillisecondsFromRateString(const std::string& rateText, double fallbackRate = 59.94);
+void VideoFormatDimensions(const std::string& formatName, unsigned& width, unsigned& height);
+std::filesystem::path FindConfigFile(const std::filesystem::path& relativePath = "config/runtime-host.json");
+std::filesystem::path FindRepoPath(const std::filesystem::path& relativePath);
+}

apps/RenderCadenceCompositor/app/RenderCadenceApp.h

@@ -0,0 +1,241 @@
+#pragma once
+
+#include "AppConfig.h"
+#include "AppConfigProvider.h"
+#include "RuntimeLayerController.h"
+#include "../logging/Logger.h"
+#include "../control/RuntimeStateJson.h"
+#include "../telemetry/TelemetryHealthMonitor.h"
+#include "../video/DeckLinkOutput.h"
+#include "../video/DeckLinkOutputThread.h"
+
+#include <chrono>
+#include <filesystem>
+#include <string>
+#include <thread>
+#include <type_traits>
+
+namespace RenderCadenceCompositor
+{
+namespace detail
+{
+template <typename RenderThread>
+auto StartRenderThread(RenderThread& renderThread, std::string& error, int) -> decltype(renderThread.Start(error), bool())
+{
+	return renderThread.Start(error);
+}
+
+template <typename RenderThread>
+bool StartRenderThreadWithoutError(RenderThread& renderThread, std::true_type)
+{
+	return renderThread.Start();
+}
+
+template <typename RenderThread>
+bool StartRenderThreadWithoutError(RenderThread& renderThread, std::false_type)
+{
+	renderThread.Start();
+	return true;
+}
+
+template <typename RenderThread>
+auto StartRenderThread(RenderThread& renderThread, std::string&, long) -> decltype(renderThread.Start(), bool())
+{
+	return StartRenderThreadWithoutError(renderThread, std::is_same<decltype(renderThread.Start()), bool>());
+}
+}
+
+template <typename RenderThread, typename SystemFrameExchange>
+class RenderCadenceApp
+{
+public:
+	RenderCadenceApp(RenderThread& renderThread, SystemFrameExchange& frameExchange, AppConfig config = DefaultAppConfig()) :
+		mRenderThread(renderThread),
+		mFrameExchange(frameExchange),
+		mConfig(config),
+		mOutputThread(mOutput, mFrameExchange, mConfig.outputThread),
+		mTelemetryHealth(mConfig.telemetry),
+		mRuntimeLayers([this](const std::vector<RuntimeRenderLayerModel>& layers) {
+			mRenderThread.SubmitRuntimeRenderLayers(layers);
+		})
+	{
+	}
+
+	RenderCadenceApp(const RenderCadenceApp&) = delete;
+	RenderCadenceApp& operator=(const RenderCadenceApp&) = delete;
+
+	~RenderCadenceApp()
+	{
+		Stop();
+	}
+
+	bool Start(std::string& error)
+	{
+		mRuntimeLayers.Initialize(
+			mConfig.shaderLibrary,
+			static_cast<unsigned>(mConfig.maxTemporalHistoryFrames),
+			mConfig.runtimeShaderId);
+
+		Log("app", "Starting render thread.");
+		if (!detail::StartRenderThread(mRenderThread, error, 0))
+		{
+			LogError("app", "Render thread start failed: " + error);
+			Stop();
+			return false;
+		}
+		mRuntimeLayers.StartStartupBuild(mConfig.runtimeShaderId);
+
+		Log("app", "Waiting for rendered warmup frames.");
+		if (!mFrameExchange.WaitForCompletedDepth(mConfig.warmupCompletedFrames, mConfig.warmupTimeout))
+		{
+			error = "Timed out waiting for rendered warmup frames.";
+			LogError("app", error);
+			Stop();
+			return false;
+		}
+
+		StartOptionalVideoOutput();
+		mTelemetryHealth.Start(mFrameExchange, mOutput, mOutputThread, mRenderThread);
+		StartHttpServer();
+		Log("app", "RenderCadenceCompositor started.");
+		mStarted = true;
+		return true;
+	}
+
+	void Stop()
+	{
+		mHttpServer.Stop();
+		mTelemetryHealth.Stop();
+		mOutputThread.Stop();
+		mOutput.Stop();
+		mRuntimeLayers.Stop();
+		mRenderThread.Stop();
+		mOutput.ReleaseResources();
+		if (mStarted)
+			Log("app", "RenderCadenceCompositor shutdown complete.");
+		mStarted = false;
+	}
+
+	bool Started() const { return mStarted; }
+	const DeckLinkOutput& Output() const { return mOutput; }
+
+private:
+	void StartOptionalVideoOutput()
+	{
+		std::string outputError;
+		Log("app", "Initializing optional DeckLink output.");
+		if (!mOutput.Initialize(
+			mConfig.deckLink,
+			[this](const VideoIOCompletion& completion) {
+				mFrameExchange.ReleaseScheduledByBytes(completion.outputFrameBuffer);
+			},
+			outputError))
+		{
+			DisableVideoOutput("DeckLink output unavailable: " + outputError);
+			return;
+		}
+
+		Log("app", "Starting DeckLink output thread.");
+		if (!mOutputThread.Start())
+		{
+			DisableVideoOutput("DeckLink output thread failed to start.");
+			return;
+		}
+
+		Log("app", "Waiting for DeckLink preroll frames.");
+		if (!WaitForPreroll())
+		{
+			DisableVideoOutput("Timed out waiting for DeckLink preroll frames.");
+			return;
+		}
+
+		Log("app", "Starting DeckLink scheduled playback.");
+		if (!mOutput.StartScheduledPlayback(outputError))
+		{
+			DisableVideoOutput("DeckLink scheduled playback failed: " + outputError);
+			return;
+		}
+
+		mVideoOutputEnabled = true;
+		mVideoOutputStatus = "DeckLink scheduled output running.";
+		Log("app", mVideoOutputStatus);
+	}
+
+	void DisableVideoOutput(const std::string& reason)
+	{
+		mOutputThread.Stop();
+		mOutput.Stop();
+		mOutput.ReleaseResources();
+		mFrameExchange.Clear();
+		mVideoOutputEnabled = false;
+		mVideoOutputStatus = reason;
+		LogWarning("app", reason + " Continuing without video output.");
+	}
+
+	void StartHttpServer()
+	{
+		HttpControlServerCallbacks callbacks;
+		callbacks.getStateJson = [this]() {
+			return BuildStateJson();
+		};
+		callbacks.addLayer = [this](const std::string& body) {
+			return mRuntimeLayers.HandleAddLayer(body);
+		};
+		callbacks.removeLayer = [this](const std::string& body) {
+			return mRuntimeLayers.HandleRemoveLayer(body);
+		};
+
+		std::string error;
+		if (!mHttpServer.Start(
+			FindRepoPath("ui/dist"),
+			FindRepoPath("docs"),
+			mConfig.http,
+			callbacks,
+			error))
+		{
+			LogWarning("http", "HTTP control server did not start: " + error);
+			return;
+		}
+	}
+
+	std::string BuildStateJson()
+	{
+		CadenceTelemetrySnapshot telemetry = mHttpTelemetry.Sample(mFrameExchange, mOutput, mOutputThread, mRenderThread);
+		RuntimeLayerModelSnapshot layerSnapshot = mRuntimeLayers.Snapshot(telemetry);
+		return RuntimeStateToJson(RuntimeStateJsonInput{
+			mConfig,
+			telemetry,
+			mHttpServer.Port(),
+			mVideoOutputEnabled,
+			mVideoOutputStatus,
+			mRuntimeLayers.ShaderCatalog(),
+			layerSnapshot
+		});
+	}
+
+	bool WaitForPreroll() const
+	{
+		const auto deadline = std::chrono::steady_clock::now() + mConfig.prerollTimeout;
+		while (std::chrono::steady_clock::now() < deadline)
+		{
+			if (mFrameExchange.Metrics().scheduledCount >= mConfig.outputThread.targetBufferedFrames)
+				return true;
+			std::this_thread::sleep_for(mConfig.prerollPoll);
+		}
+		return false;
+	}
+
+	RenderThread& mRenderThread;
+	SystemFrameExchange& mFrameExchange;
+	AppConfig mConfig;
+	DeckLinkOutput mOutput;
+	DeckLinkOutputThread<SystemFrameExchange> mOutputThread;
+	TelemetryHealthMonitor mTelemetryHealth;
+	CadenceTelemetry mHttpTelemetry;
+	HttpControlServer mHttpServer;
+	RuntimeLayerController mRuntimeLayers;
+	bool mStarted = false;
+	bool mVideoOutputEnabled = false;
+	std::string mVideoOutputStatus = "DeckLink output not started.";
+};
+}

apps/RenderCadenceCompositor/app/RuntimeLayerController.cpp

@@ -0,0 +1,272 @@
+#include "RuntimeLayerController.h"
+
+#include "AppConfigProvider.h"
+#include "RuntimeJson.h"
+#include "../logging/Logger.h"
+
+#include <filesystem>
+
+namespace RenderCadenceCompositor
+{
+RuntimeLayerController::RuntimeLayerController(RenderLayerPublisher publisher) :
+	mPublisher(std::move(publisher))
+{
+}
+
+RuntimeLayerController::~RuntimeLayerController()
+{
+	Stop();
+}
+
+void RuntimeLayerController::SetPublisher(RenderLayerPublisher publisher)
+{
+	mPublisher = std::move(publisher);
+}
+
+void RuntimeLayerController::Initialize(const std::string& shaderLibrary, unsigned maxTemporalHistoryFrames, std::string& runtimeShaderId)
+{
+	LoadSupportedShaderCatalog(shaderLibrary, maxTemporalHistoryFrames);
+	InitializeLayerModel(runtimeShaderId);
+}
+
+void RuntimeLayerController::StartStartupBuild(const std::string& runtimeShaderId)
+{
+	if (runtimeShaderId.empty())
+	{
+		Log("runtime-shader", "Runtime shader build disabled.");
+		return;
+	}
+
+	Log("runtime-shader", "Starting background Slang build for shader '" + runtimeShaderId + "'.");
+	const std::string layerId = FirstRuntimeLayerId();
+	if (!layerId.empty())
+		StartLayerShaderBuild(layerId, runtimeShaderId);
+}
+
+void RuntimeLayerController::Stop()
+{
+	StopAllRuntimeShaderBuilds();
+}
+
+ControlActionResult RuntimeLayerController::HandleAddLayer(const std::string& body)
+{
+	CleanupRetiredShaderBuilds();
+
+	std::string shaderId;
+	std::string error;
+	if (!ExtractStringField(body, "shaderId", shaderId, error))
+		return { false, error };
+
+	std::string layerId;
+	{
+		std::lock_guard<std::mutex> lock(mRuntimeLayerMutex);
+		if (!mRuntimeLayerModel.AddLayer(mShaderCatalog, shaderId, layerId, error))
+			return { false, error };
+	}
+
+	Log("runtime-shader", "Layer added: " + layerId + " shader=" + shaderId);
+	StartLayerShaderBuild(layerId, shaderId);
+	return { true, std::string() };
+}
+
+ControlActionResult RuntimeLayerController::HandleRemoveLayer(const std::string& body)
+{
+	CleanupRetiredShaderBuilds();
+
+	std::string layerId;
+	std::string error;
+	if (!ExtractStringField(body, "layerId", layerId, error))
+		return { false, error };
+
+	{
+		std::lock_guard<std::mutex> lock(mRuntimeLayerMutex);
+		if (!mRuntimeLayerModel.RemoveLayer(layerId, error))
+			return { false, error };
+	}
+
+	Log("runtime-shader", "Layer removed: " + layerId);
+	RetireLayerShaderBuild(layerId);
+	PublishRuntimeRenderLayers();
+	return { true, std::string() };
+}
+
+RuntimeLayerModelSnapshot RuntimeLayerController::Snapshot(const CadenceTelemetrySnapshot& telemetry) const
+{
+	std::lock_guard<std::mutex> lock(mRuntimeLayerMutex);
+	RuntimeLayerModelSnapshot snapshot = mRuntimeLayerModel.Snapshot();
+	if (telemetry.shaderBuildFailures > 0)
+	{
+		snapshot.compileSucceeded = false;
+		snapshot.compileMessage = "Runtime shader GL commit failed; see logs for details.";
+	}
+	return snapshot;
+}
+
+void RuntimeLayerController::LoadSupportedShaderCatalog(const std::string& shaderLibrary, unsigned maxTemporalHistoryFrames)
+{
+	const std::filesystem::path shaderRoot = FindRepoPath(shaderLibrary);
+	std::string error;
+	if (!mShaderCatalog.Load(shaderRoot, maxTemporalHistoryFrames, error))
+	{
+		LogWarning("runtime-shader", "Supported shader catalog is empty: " + error);
+		return;
+	}
+
+	Log("runtime-shader", "Supported shader catalog loaded with " + std::to_string(mShaderCatalog.Shaders().size()) + " shader(s).");
+}
+
+void RuntimeLayerController::InitializeLayerModel(std::string& runtimeShaderId)
+{
+	std::lock_guard<std::mutex> lock(mRuntimeLayerMutex);
+	std::string error;
+	if (!mRuntimeLayerModel.InitializeSingleLayer(mShaderCatalog, runtimeShaderId, error))
+	{
+		LogWarning("runtime-shader", error + " Runtime shader build disabled.");
+		runtimeShaderId.clear();
+		mRuntimeLayerModel.Clear();
+	}
+}
+
+void RuntimeLayerController::StartLayerShaderBuild(const std::string& layerId, const std::string& shaderId)
+{
+	CleanupRetiredShaderBuilds();
+	RetireLayerShaderBuild(layerId);
+
+	{
+		std::lock_guard<std::mutex> lock(mRuntimeLayerMutex);
+		std::string error;
+		mRuntimeLayerModel.MarkBuildStarted(layerId, "Runtime Slang build started for shader '" + shaderId + "'.", error);
+	}
+
+	auto bridge = std::make_unique<RuntimeShaderBridge>();
+	RuntimeShaderBridge* bridgePtr = bridge.get();
+	{
+		std::lock_guard<std::mutex> lock(mShaderBuildMutex);
+		mShaderBuilds[layerId] = std::move(bridge);
+	}
+
+	bridgePtr->Start(
+		layerId,
+		shaderId,
+		[this](const RuntimeShaderArtifact& artifact) {
+			if (MarkRuntimeBuildReady(artifact))
+				PublishRuntimeRenderLayers();
+		},
+		[this, layerId](const std::string& message) {
+			MarkRuntimeBuildFailedForLayer(layerId, message);
+			LogError("runtime-shader", "Runtime Slang build failed: " + message);
+		});
+}
+
+void RuntimeLayerController::RetireLayerShaderBuild(const std::string& layerId)
+{
+	std::unique_ptr<RuntimeShaderBridge> bridge;
+	{
+		std::lock_guard<std::mutex> lock(mShaderBuildMutex);
+		auto bridgeIt = mShaderBuilds.find(layerId);
+		if (bridgeIt == mShaderBuilds.end())
+			return;
+		bridge = std::move(bridgeIt->second);
+		mShaderBuilds.erase(bridgeIt);
+		bridge->RequestStop();
+		mRetiredShaderBuilds.push_back(std::move(bridge));
+	}
+}
+
+void RuntimeLayerController::CleanupRetiredShaderBuilds()
+{
+	std::vector<std::unique_ptr<RuntimeShaderBridge>> readyToStop;
+	{
+		std::lock_guard<std::mutex> lock(mShaderBuildMutex);
+		for (auto it = mRetiredShaderBuilds.begin(); it != mRetiredShaderBuilds.end();)
+		{
+			if ((*it)->CanStopWithoutWaiting())
+			{
+				readyToStop.push_back(std::move(*it));
+				it = mRetiredShaderBuilds.erase(it);
+				continue;
+			}
+			++it;
+		}
+	}
+
+	for (std::unique_ptr<RuntimeShaderBridge>& bridge : readyToStop)
+		bridge->Stop();
+}
+
+void RuntimeLayerController::StopAllRuntimeShaderBuilds()
+{
+	std::map<std::string, std::unique_ptr<RuntimeShaderBridge>> builds;
+	std::vector<std::unique_ptr<RuntimeShaderBridge>> retiredBuilds;
+	{
+		std::lock_guard<std::mutex> lock(mShaderBuildMutex);
+		builds.swap(mShaderBuilds);
+		retiredBuilds.swap(mRetiredShaderBuilds);
+	}
+	for (auto& entry : builds)
+		entry.second->Stop();
+	for (auto& bridge : retiredBuilds)
+		bridge->Stop();
+}
+
+void RuntimeLayerController::PublishRuntimeRenderLayers()
+{
+	if (!mPublisher)
+		return;
+
+	std::vector<RuntimeRenderLayerModel> renderLayers;
+	{
+		std::lock_guard<std::mutex> lock(mRuntimeLayerMutex);
+		renderLayers = mRuntimeLayerModel.Snapshot().renderLayers;
+	}
+	mPublisher(renderLayers);
+}
+
+bool RuntimeLayerController::MarkRuntimeBuildReady(const RuntimeShaderArtifact& artifact)
+{
+	std::lock_guard<std::mutex> lock(mRuntimeLayerMutex);
+	std::string error;
+	if (!mRuntimeLayerModel.MarkBuildReady(artifact, error))
+	{
+		LogWarning("runtime-shader", error);
+		return false;
+	}
+	return true;
+}
+
+void RuntimeLayerController::MarkRuntimeBuildFailedForLayer(const std::string& layerId, const std::string& message)
+{
+	std::lock_guard<std::mutex> lock(mRuntimeLayerMutex);
+	std::string error;
+	if (!mRuntimeLayerModel.MarkBuildFailed(layerId, message, error))
+		LogWarning("runtime-shader", error);
+}
+
+std::string RuntimeLayerController::FirstRuntimeLayerId() const
+{
+	std::lock_guard<std::mutex> lock(mRuntimeLayerMutex);
+	return mRuntimeLayerModel.FirstLayerId();
+}
+
+bool RuntimeLayerController::ExtractStringField(const std::string& body, const char* fieldName, std::string& value, std::string& error)
+{
+	JsonValue root;
+	std::string parseError;
+	if (!ParseJson(body.empty() ? "{}" : body, root, parseError) || !root.isObject())
+	{
+		error = parseError.empty() ? "Request body must be a JSON object." : parseError;
+		return false;
+	}
+
+	const JsonValue* field = root.find(fieldName);
+	if (!field || !field->isString() || field->asString().empty())
+	{
+		error = std::string("Request field '") + fieldName + "' must be a non-empty string.";
+		return false;
+	}
+
+	value = field->asString();
+	error.clear();
+	return true;
+}
+}

apps/RenderCadenceCompositor/app/RuntimeLayerController.h

@@ -0,0 +1,61 @@
+#pragma once
+
+#include "../control/ControlActionResult.h"
+#include "../runtime/RuntimeLayerModel.h"
+#include "../runtime/RuntimeShaderBridge.h"
+#include "../runtime/SupportedShaderCatalog.h"
+#include "../telemetry/CadenceTelemetry.h"
+
+#include <functional>
+#include <map>
+#include <memory>
+#include <mutex>
+#include <string>
+#include <vector>
+
+namespace RenderCadenceCompositor
+{
+class RuntimeLayerController
+{
+public:
+	using RenderLayerPublisher = std::function<void(const std::vector<RuntimeRenderLayerModel>&)>;
+
+	explicit RuntimeLayerController(RenderLayerPublisher publisher = RenderLayerPublisher());
+	RuntimeLayerController(const RuntimeLayerController&) = delete;
+	RuntimeLayerController& operator=(const RuntimeLayerController&) = delete;
+	~RuntimeLayerController();
+
+	void SetPublisher(RenderLayerPublisher publisher);
+	void Initialize(const std::string& shaderLibrary, unsigned maxTemporalHistoryFrames, std::string& runtimeShaderId);
+	void StartStartupBuild(const std::string& runtimeShaderId);
+	void Stop();
+
+	ControlActionResult HandleAddLayer(const std::string& body);
+	ControlActionResult HandleRemoveLayer(const std::string& body);
+
+	RuntimeLayerModelSnapshot Snapshot(const CadenceTelemetrySnapshot& telemetry) const;
+	const SupportedShaderCatalog& ShaderCatalog() const { return mShaderCatalog; }
+
+private:
+	void LoadSupportedShaderCatalog(const std::string& shaderLibrary, unsigned maxTemporalHistoryFrames);
+	void InitializeLayerModel(std::string& runtimeShaderId);
+	void StartLayerShaderBuild(const std::string& layerId, const std::string& shaderId);
+	void RetireLayerShaderBuild(const std::string& layerId);
+	void CleanupRetiredShaderBuilds();
+	void StopAllRuntimeShaderBuilds();
+	void PublishRuntimeRenderLayers();
+	bool MarkRuntimeBuildReady(const RuntimeShaderArtifact& artifact);
+	void MarkRuntimeBuildFailedForLayer(const std::string& layerId, const std::string& message);
+
+	std::string FirstRuntimeLayerId() const;
+	static bool ExtractStringField(const std::string& body, const char* fieldName, std::string& value, std::string& error);
+
+	RenderLayerPublisher mPublisher;
+	SupportedShaderCatalog mShaderCatalog;
+	mutable std::mutex mRuntimeLayerMutex;
+	RuntimeLayerModel mRuntimeLayerModel;
+	std::mutex mShaderBuildMutex;
+	std::map<std::string, std::unique_ptr<RuntimeShaderBridge>> mShaderBuilds;
+	std::vector<std::unique_ptr<RuntimeShaderBridge>> mRetiredShaderBuilds;
+};
+}

apps/RenderCadenceCompositor/control/ControlActionResult.h

@@ -0,0 +1,12 @@
+#pragma once
+
+#include <string>
+
+namespace RenderCadenceCompositor
+{
+struct ControlActionResult
+{
+	bool ok = false;
+	std::string error;
+};
+}

apps/RenderCadenceCompositor/control/HttpControlServer.cpp

@@ -0,0 +1,716 @@
+#include "HttpControlServer.h"
+
+#include "../json/JsonWriter.h"
+#include "../logging/Logger.h"
+
+#include <ws2tcpip.h>
+
+#include <algorithm>
+#include <array>
+#include <cctype>
+#include <cstdint>
+#include <fstream>
+#include <sstream>
+#include <vector>
+
+namespace RenderCadenceCompositor
+{
+namespace
+{
+bool InitializeWinsock(std::string& error)
+{
+	WSADATA wsaData = {};
+	const int result = WSAStartup(MAKEWORD(2, 2), &wsaData);
+	if (result != 0)
+	{
+		error = "WSAStartup failed.";
+		return false;
+	}
+	return true;
+}
+
+bool IsKnownPostEndpoint(const std::string& path)
+{
+	return path == "/api/layers/add"
+		|| path == "/api/layers/remove"
+		|| path == "/api/layers/move"
+		|| path == "/api/layers/reorder"
+		|| path == "/api/layers/set-bypass"
+		|| path == "/api/layers/set-shader"
+		|| path == "/api/layers/update-parameter"
+		|| path == "/api/layers/reset-parameters"
+		|| path == "/api/stack-presets/save"
+		|| path == "/api/stack-presets/load"
+		|| path == "/api/reload"
+		|| path == "/api/screenshot";
+}
+
+std::array<uint8_t, 20> Sha1(const std::string& input)
+{
+	auto leftRotate = [](uint32_t value, uint32_t bits) {
+		return (value << bits) | (value >> (32U - bits));
+	};
+
+	std::vector<uint8_t> data(input.begin(), input.end());
+	const uint64_t bitLength = static_cast<uint64_t>(data.size()) * 8ULL;
+	data.push_back(0x80);
+	while ((data.size() % 64) != 56)
+		data.push_back(0);
+	for (int shift = 56; shift >= 0; shift -= 8)
+		data.push_back(static_cast<uint8_t>((bitLength >> shift) & 0xff));
+
+	uint32_t h0 = 0x67452301;
+	uint32_t h1 = 0xefcdab89;
+	uint32_t h2 = 0x98badcfe;
+	uint32_t h3 = 0x10325476;
+	uint32_t h4 = 0xc3d2e1f0;
+
+	for (std::size_t offset = 0; offset < data.size(); offset += 64)
+	{
+		uint32_t words[80] = {};
+		for (std::size_t i = 0; i < 16; ++i)
+		{
+			const std::size_t index = offset + i * 4;
+			words[i] = (static_cast<uint32_t>(data[index]) << 24)
+				| (static_cast<uint32_t>(data[index + 1]) << 16)
+				| (static_cast<uint32_t>(data[index + 2]) << 8)
+				| static_cast<uint32_t>(data[index + 3]);
+		}
+		for (std::size_t i = 16; i < 80; ++i)
+			words[i] = leftRotate(words[i - 3] ^ words[i - 8] ^ words[i - 14] ^ words[i - 16], 1);
+
+		uint32_t a = h0;
+		uint32_t b = h1;
+		uint32_t c = h2;
+		uint32_t d = h3;
+		uint32_t e = h4;
+
+		for (std::size_t i = 0; i < 80; ++i)
+		{
+			uint32_t f = 0;
+			uint32_t k = 0;
+			if (i < 20)
+			{
+				f = (b & c) | ((~b) & d);
+				k = 0x5a827999;
+			}
+			else if (i < 40)
+			{
+				f = b ^ c ^ d;
+				k = 0x6ed9eba1;
+			}
+			else if (i < 60)
+			{
+				f = (b & c) | (b & d) | (c & d);
+				k = 0x8f1bbcdc;
+			}
+			else
+			{
+				f = b ^ c ^ d;
+				k = 0xca62c1d6;
+			}
+
+			const uint32_t temp = leftRotate(a, 5) + f + e + k + words[i];
+			e = d;
+			d = c;
+			c = leftRotate(b, 30);
+			b = a;
+			a = temp;
+		}
+
+		h0 += a;
+		h1 += b;
+		h2 += c;
+		h3 += d;
+		h4 += e;
+	}
+
+	std::array<uint8_t, 20> digest = {};
+	const uint32_t parts[] = { h0, h1, h2, h3, h4 };
+	for (std::size_t i = 0; i < 5; ++i)
+	{
+		digest[i * 4] = static_cast<uint8_t>((parts[i] >> 24) & 0xff);
+		digest[i * 4 + 1] = static_cast<uint8_t>((parts[i] >> 16) & 0xff);
+		digest[i * 4 + 2] = static_cast<uint8_t>((parts[i] >> 8) & 0xff);
+		digest[i * 4 + 3] = static_cast<uint8_t>(parts[i] & 0xff);
+	}
+	return digest;
+}
+
+std::string Base64Encode(const uint8_t* data, std::size_t size)
+{
+	static constexpr char kAlphabet[] = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+	std::string output;
+	output.reserve(((size + 2) / 3) * 4);
+	for (std::size_t i = 0; i < size; i += 3)
+	{
+		const uint32_t a = data[i];
+		const uint32_t b = i + 1 < size ? data[i + 1] : 0;
+		const uint32_t c = i + 2 < size ? data[i + 2] : 0;
+		const uint32_t triple = (a << 16) | (b << 8) | c;
+		output.push_back(kAlphabet[(triple >> 18) & 0x3f]);
+		output.push_back(kAlphabet[(triple >> 12) & 0x3f]);
+		output.push_back(i + 1 < size ? kAlphabet[(triple >> 6) & 0x3f] : '=');
+		output.push_back(i + 2 < size ? kAlphabet[triple & 0x3f] : '=');
+	}
+	return output;
+}
+}
+
+UniqueSocket::UniqueSocket(SOCKET socket) :
+	mSocket(socket)
+{
+}
+
+UniqueSocket::~UniqueSocket()
+{
+	reset();
+}
+
+UniqueSocket::UniqueSocket(UniqueSocket&& other) noexcept :
+	mSocket(other.release())
+{
+}
+
+UniqueSocket& UniqueSocket::operator=(UniqueSocket&& other) noexcept
+{
+	if (this != &other)
+		reset(other.release());
+	return *this;
+}
+
+SOCKET UniqueSocket::release()
+{
+	const SOCKET socket = mSocket;
+	mSocket = INVALID_SOCKET;
+	return socket;
+}
+
+void UniqueSocket::reset(SOCKET socket)
+{
+	if (valid())
+		closesocket(mSocket);
+	mSocket = socket;
+}
+
+HttpControlServer::~HttpControlServer()
+{
+	Stop();
+}
+
+bool HttpControlServer::Start(
+	const std::filesystem::path& uiRoot,
+	const std::filesystem::path& docsRoot,
+	HttpControlServerConfig config,
+	HttpControlServerCallbacks callbacks,
+	std::string& error)
+{
+	Stop();
+
+	if (!InitializeWinsock(error))
+		return false;
+	mWinsockStarted = true;
+
+	mUiRoot = uiRoot;
+	mDocsRoot = docsRoot;
+	mConfig = config;
+	mCallbacks = std::move(callbacks);
+
+	mListenSocket.reset(socket(AF_INET, SOCK_STREAM, IPPROTO_TCP));
+	if (!mListenSocket.valid())
+	{
+		error = "Could not create HTTP control server socket.";
+		Stop();
+		return false;
+	}
+
+	u_long nonBlocking = 1;
+	ioctlsocket(mListenSocket.get(), FIONBIO, &nonBlocking);
+
+	sockaddr_in address = {};
+	address.sin_family = AF_INET;
+	address.sin_addr.s_addr = htonl(INADDR_LOOPBACK);
+
+	bool bound = false;
+	for (unsigned short offset = 0; offset < mConfig.portSearchCount; ++offset)
+	{
+		address.sin_port = htons(static_cast<u_short>(mConfig.preferredPort + offset));
+		if (bind(mListenSocket.get(), reinterpret_cast<sockaddr*>(&address), sizeof(address)) == 0)
+		{
+			mPort = static_cast<unsigned short>(mConfig.preferredPort + offset);
+			bound = true;
+			break;
+		}
+	}
+
+	if (!bound)
+	{
+		error = "Could not bind HTTP control server to loopback.";
+		Stop();
+		return false;
+	}
+
+	if (listen(mListenSocket.get(), SOMAXCONN) != 0)
+	{
+		error = "Could not listen on HTTP control server socket.";
+		Stop();
+		return false;
+	}
+
+	mRunning.store(true, std::memory_order_release);
+	mThread = std::thread([this]() { ThreadMain(); });
+	Log("http", "HTTP control server listening on http://127.0.0.1:" + std::to_string(mPort));
+	return true;
+}
+
+void HttpControlServer::Stop()
+{
+	mRunning.store(false, std::memory_order_release);
+	mListenSocket.reset();
+
+	if (mThread.joinable())
+		mThread.join();
+
+	std::vector<std::thread> clientThreads;
+	{
+		std::lock_guard<std::mutex> lock(mClientThreadsMutex);
+		clientThreads.swap(mClientThreads);
+		for (std::thread& thread : mFinishedClientThreads)
+			clientThreads.push_back(std::move(thread));
+		mFinishedClientThreads.clear();
+	}
+	for (std::thread& thread : clientThreads)
+	{
+		if (thread.joinable())
+			thread.join();
+	}
+
+	if (mWinsockStarted)
+	{
+		WSACleanup();
+		mWinsockStarted = false;
+	}
+	mPort = 0;
+}
+
+HttpControlServer::HttpResponse HttpControlServer::RouteRequestForTest(const HttpRequest& request) const
+{
+	return RouteRequest(request);
+}
+
+void HttpControlServer::SetCallbacksForTest(HttpControlServerCallbacks callbacks)
+{
+	mCallbacks = std::move(callbacks);
+}
+
+void HttpControlServer::SetRootsForTest(const std::filesystem::path& uiRoot, const std::filesystem::path& docsRoot)
+{
+	mUiRoot = uiRoot;
+	mDocsRoot = docsRoot;
+}
+
+void HttpControlServer::ThreadMain()
+{
+	while (mRunning.load(std::memory_order_acquire))
+	{
+		JoinFinishedClientThreads();
+		TryAcceptClient();
+		std::this_thread::sleep_for(mConfig.idleSleep);
+	}
+}
+
+bool HttpControlServer::TryAcceptClient()
+{
+	sockaddr_in clientAddress = {};
+	int addressSize = sizeof(clientAddress);
+	UniqueSocket clientSocket(accept(mListenSocket.get(), reinterpret_cast<sockaddr*>(&clientAddress), &addressSize));
+	if (!clientSocket.valid())
+		return false;
+
+	return HandleClient(std::move(clientSocket));
+}
+
+bool HttpControlServer::HandleClient(UniqueSocket clientSocket)
+{
+	char buffer[16384];
+	const int received = recv(clientSocket.get(), buffer, sizeof(buffer), 0);
+	if (received <= 0)
+		return false;
+
+	HttpRequest request;
+	if (!ParseHttpRequest(std::string(buffer, buffer + received), request))
+		return SendResponse(clientSocket.get(), TextResponse("400 Bad Request", "Bad Request"));
+
+	if (request.path == "/ws")
+		return HandleWebSocketClient(std::move(clientSocket), request);
+
+	return SendResponse(clientSocket.get(), RouteRequest(request));
+}
+
+bool HttpControlServer::HandleWebSocketClient(UniqueSocket clientSocket, const HttpRequest& request)
+{
+	const auto keyIt = request.headers.find("sec-websocket-key");
+	if (keyIt == request.headers.end() || keyIt->second.empty())
+		return SendResponse(clientSocket.get(), TextResponse("400 Bad Request", "Missing WebSocket key"));
+
+	std::ostringstream stream;
+	stream << "HTTP/1.1 101 Switching Protocols\r\n"
+		<< "Upgrade: websocket\r\n"
+		<< "Connection: Upgrade\r\n"
+		<< "Sec-WebSocket-Accept: " << WebSocketAcceptKey(keyIt->second) << "\r\n\r\n";
+	const std::string response = stream.str();
+	if (send(clientSocket.get(), response.c_str(), static_cast<int>(response.size()), 0) != static_cast<int>(response.size()))
+		return false;
+
+	u_long nonBlocking = 1;
+	ioctlsocket(clientSocket.get(), FIONBIO, &nonBlocking);
+
+	std::thread thread([this, socket = std::move(clientSocket)]() mutable {
+		WebSocketClientMain(std::move(socket));
+	});
+	{
+		std::lock_guard<std::mutex> lock(mClientThreadsMutex);
+		mClientThreads.push_back(std::move(thread));
+	}
+	return true;
+}
+
+void HttpControlServer::WebSocketClientMain(UniqueSocket clientSocket)
+{
+	std::string previousState;
+	while (mRunning.load(std::memory_order_acquire))
+	{
+		const std::string state = mCallbacks.getStateJson ? mCallbacks.getStateJson() : "{}";
+		if (state != previousState)
+		{
+			if (!SendWebSocketText(clientSocket.get(), state))
+				break;
+			previousState = state;
+		}
+		std::this_thread::sleep_for(std::chrono::milliseconds(250));
+	}
+
+	std::lock_guard<std::mutex> lock(mClientThreadsMutex);
+	const std::thread::id currentId = std::this_thread::get_id();
+	for (auto it = mClientThreads.begin(); it != mClientThreads.end(); ++it)
+	{
+		if (it->get_id() != currentId)
+			continue;
+		mFinishedClientThreads.push_back(std::move(*it));
+		mClientThreads.erase(it);
+		break;
+	}
+}
+
+void HttpControlServer::JoinFinishedClientThreads()
+{
+	std::vector<std::thread> finished;
+	{
+		std::lock_guard<std::mutex> lock(mClientThreadsMutex);
+		finished.swap(mFinishedClientThreads);
+	}
+	for (std::thread& thread : finished)
+	{
+		if (thread.joinable())
+			thread.join();
+	}
+}
+
+bool HttpControlServer::SendResponse(SOCKET clientSocket, const HttpResponse& response) const
+{
+	std::ostringstream stream;
+	stream << "HTTP/1.1 " << response.status << "\r\n"
+		<< "Content-Type: " << response.contentType << "\r\n"
+		<< "Content-Length: " << response.body.size() << "\r\n"
+		<< "Access-Control-Allow-Origin: *\r\n"
+		<< "Connection: close\r\n\r\n"
+		<< response.body;
+
+	const std::string payload = stream.str();
+	return send(clientSocket, payload.c_str(), static_cast<int>(payload.size()), 0) == static_cast<int>(payload.size());
+}
+
+HttpControlServer::HttpResponse HttpControlServer::RouteRequest(const HttpRequest& request) const
+{
+	if (request.method == "GET")
+		return ServeGet(request);
+	if (request.method == "POST")
+		return ServePost(request);
+	if (request.method == "OPTIONS")
+		return TextResponse("204 No Content", std::string());
+	return TextResponse("404 Not Found", "Not Found");
+}
+
+HttpControlServer::HttpResponse HttpControlServer::ServeGet(const HttpRequest& request) const
+{
+	if (request.path == "/api/state")
+		return JsonResponse("200 OK", mCallbacks.getStateJson ? mCallbacks.getStateJson() : "{}");
+	if (request.path == "/openapi.yaml" || request.path == "/docs/openapi.yaml")
+		return ServeOpenApiSpec();
+	if (request.path == "/docs" || request.path == "/docs/")
+		return ServeSwaggerDocs();
+	if (request.path == "/" || request.path == "/index.html")
+		return ServeUiAsset("index.html");
+	if (request.path.rfind("/assets/", 0) == 0)
+		return ServeUiAsset(request.path.substr(1));
+	if (request.path.size() > 1)
+	{
+		const HttpResponse asset = ServeUiAsset(request.path.substr(1));
+		if (asset.status != "404 Not Found")
+			return asset;
+	}
+	return ServeUiAsset("index.html");
+}
+
+HttpControlServer::HttpResponse HttpControlServer::ServePost(const HttpRequest& request) const
+{
+	if (!IsKnownPostEndpoint(request.path))
+		return TextResponse("404 Not Found", "Not Found");
+
+	if (request.path == "/api/layers/add" && mCallbacks.addLayer)
+	{
+		const ControlActionResult result = mCallbacks.addLayer(request.body);
+		return JsonResponse(result.ok ? "200 OK" : "400 Bad Request", ActionResponse(result.ok, result.error));
+	}
+
+	if (request.path == "/api/layers/remove" && mCallbacks.removeLayer)
+	{
+		const ControlActionResult result = mCallbacks.removeLayer(request.body);
+		return JsonResponse(result.ok ? "200 OK" : "400 Bad Request", ActionResponse(result.ok, result.error));
+	}
+
+	return {
+		"400 Bad Request",
+		"application/json",
+		ActionResponse(false, "Endpoint is not implemented in RenderCadenceCompositor yet.")
+	};
+}
+
+HttpControlServer::HttpResponse HttpControlServer::ServeOpenApiSpec() const
+{
+	const std::filesystem::path path = mDocsRoot / "openapi.yaml";
+	const std::string body = LoadTextFile(path);
+	return body.empty()
+		? TextResponse("404 Not Found", "OpenAPI spec not found")
+		: HttpResponse{ "200 OK", GuessContentType(path), body };
+}
+
+HttpControlServer::HttpResponse HttpControlServer::ServeSwaggerDocs() const
+{
+	std::ostringstream html;
+	html << "<!doctype html>\n"
+		<< "<html><head><meta charset=\"utf-8\"><title>Video Shader Toys API Docs</title>\n"
+		<< "<link rel=\"stylesheet\" href=\"https://unpkg.com/swagger-ui-dist@5/swagger-ui.css\"></head>\n"
+		<< "<body><div id=\"swagger-ui\"></div>\n"
+		<< "<script src=\"https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js\"></script>\n"
+		<< "<script>SwaggerUIBundle({url:'/docs/openapi.yaml',dom_id:'#swagger-ui'});</script>\n"
+		<< "</body></html>\n";
+	return { "200 OK", "text/html", html.str() };
+}
+
+HttpControlServer::HttpResponse HttpControlServer::ServeUiAsset(const std::string& relativePath) const
+{
+	if (mUiRoot.empty())
+		return TextResponse("404 Not Found", "UI root is not configured");
+
+	const std::filesystem::path sanitizedPath = std::filesystem::path(relativePath).lexically_normal();
+	if (!IsSafeRelativePath(sanitizedPath))
+		return TextResponse("404 Not Found", "Not Found");
+
+	const std::filesystem::path path = mUiRoot / sanitizedPath;
+	const std::string body = LoadTextFile(path);
+	if (body.empty())
+		return TextResponse("404 Not Found", "Not Found");
+	return { "200 OK", GuessContentType(path), body };
+}
+
+std::string HttpControlServer::LoadTextFile(const std::filesystem::path& path) const
+{
+	std::ifstream input(path, std::ios::binary);
+	if (!input)
+		return std::string();
+
+	std::ostringstream buffer;
+	buffer << input.rdbuf();
+	return buffer.str();
+}
+
+HttpControlServer::HttpResponse HttpControlServer::JsonResponse(const std::string& status, const std::string& body)
+{
+	return { status, "application/json", body };
+}
+
+HttpControlServer::HttpResponse HttpControlServer::TextResponse(const std::string& status, const std::string& body)
+{
+	return { status, "text/plain", body };
+}
+
+HttpControlServer::HttpResponse HttpControlServer::HtmlResponse(const std::string& status, const std::string& body)
+{
+	return { status, "text/html", body };
+}
+
+std::string HttpControlServer::ActionResponse(bool ok, const std::string& error)
+{
+	JsonWriter writer;
+	writer.BeginObject();
+	writer.KeyBool("ok", ok);
+	if (!error.empty())
+		writer.KeyString("error", error);
+	writer.EndObject();
+	return writer.StringValue();
+}
+
+bool HttpControlServer::SendWebSocketText(SOCKET clientSocket, const std::string& text)
+{
+	if (clientSocket == INVALID_SOCKET)
+		return false;
+
+	std::vector<unsigned char> frame;
+	frame.reserve(text.size() + 16);
+	frame.push_back(0x81);
+	if (text.size() <= 125)
+	{
+		frame.push_back(static_cast<unsigned char>(text.size()));
+	}
+	else if (text.size() <= 0xffff)
+	{
+		frame.push_back(126);
+		frame.push_back(static_cast<unsigned char>((text.size() >> 8) & 0xff));
+		frame.push_back(static_cast<unsigned char>(text.size() & 0xff));
+	}
+	else
+	{
+		frame.push_back(127);
+		const uint64_t length = static_cast<uint64_t>(text.size());
+		for (int shift = 56; shift >= 0; shift -= 8)
+			frame.push_back(static_cast<unsigned char>((length >> shift) & 0xff));
+	}
+	frame.insert(frame.end(), text.begin(), text.end());
+
+	const char* data = reinterpret_cast<const char*>(frame.data());
+	int remaining = static_cast<int>(frame.size());
+	while (remaining > 0)
+	{
+		const int sent = send(clientSocket, data, remaining, 0);
+		if (sent <= 0)
+		{
+			const int error = WSAGetLastError();
+			if (error == WSAEWOULDBLOCK)
+			{
+				std::this_thread::sleep_for(std::chrono::milliseconds(2));
+				continue;
+			}
+			return false;
+		}
+		data += sent;
+		remaining -= sent;
+	}
+	return true;
+}
+
+std::string HttpControlServer::WebSocketAcceptKey(const std::string& clientKey)
+{
+	static constexpr const char* kWebSocketGuid = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11";
+	const std::array<uint8_t, 20> digest = Sha1(clientKey + kWebSocketGuid);
+	return Base64Encode(digest.data(), digest.size());
+}
+
+std::string HttpControlServer::GuessContentType(const std::filesystem::path& path)
+{
+	const std::string extension = ToLower(path.extension().string());
+	if (extension == ".yaml" || extension == ".yml")
+		return "application/yaml";
+	if (extension == ".json")
+		return "application/json";
+	if (extension == ".js" || extension == ".mjs")
+		return "text/javascript";
+	if (extension == ".css")
+		return "text/css";
+	if (extension == ".html" || extension == ".htm")
+		return "text/html";
+	if (extension == ".svg")
+		return "image/svg+xml";
+	if (extension == ".png")
+		return "image/png";
+	if (extension == ".jpg" || extension == ".jpeg")
+		return "image/jpeg";
+	if (extension == ".ico")
+		return "image/x-icon";
+	if (extension == ".map")
+		return "application/json";
+	return "text/plain";
+}
+
+bool HttpControlServer::IsSafeRelativePath(const std::filesystem::path& path)
+{
+	if (path.empty() || path.is_absolute())
+		return false;
+
+	for (const std::filesystem::path& part : path)
+	{
+		if (part == "..")
+			return false;
+	}
+	return true;
+}
+
+std::string HttpControlServer::ToLower(std::string text)
+{
+	std::transform(text.begin(), text.end(), text.begin(), [](unsigned char character) {
+		return static_cast<char>(std::tolower(character));
+	});
+	return text;
+}
+
+bool HttpControlServer::ParseHttpRequest(const std::string& rawRequest, HttpRequest& request)
+{
+	const std::size_t requestLineEnd = rawRequest.find("\r\n");
+	if (requestLineEnd == std::string::npos)
+		return false;
+
+	const std::string requestLine = rawRequest.substr(0, requestLineEnd);
+	const std::size_t methodEnd = requestLine.find(' ');
+	if (methodEnd == std::string::npos)
+		return false;
+
+	const std::size_t pathEnd = requestLine.find(' ', methodEnd + 1);
+	if (pathEnd == std::string::npos)
+		return false;
+
+	request.method = requestLine.substr(0, methodEnd);
+	request.path = requestLine.substr(methodEnd + 1, pathEnd - methodEnd - 1);
+	request.headers.clear();
+
+	const std::size_t queryStart = request.path.find('?');
+	if (queryStart != std::string::npos)
+		request.path = request.path.substr(0, queryStart);
+
+	const std::size_t headersStart = requestLineEnd + 2;
+	const std::size_t bodySeparator = rawRequest.find("\r\n\r\n", headersStart);
+	const std::size_t headersEnd = bodySeparator == std::string::npos ? rawRequest.size() : bodySeparator;
+
+	for (std::size_t lineStart = headersStart; lineStart < headersEnd;)
+	{
+		const std::size_t lineEnd = rawRequest.find("\r\n", lineStart);
+		const std::size_t currentLineEnd = lineEnd == std::string::npos ? headersEnd : (std::min)(lineEnd, headersEnd);
+		const std::string line = rawRequest.substr(lineStart, currentLineEnd - lineStart);
+		const std::size_t separator = line.find(':');
+		if (separator != std::string::npos)
+		{
+			const std::string key = ToLower(line.substr(0, separator));
+			std::string value = line.substr(separator + 1);
+			const std::size_t first = value.find_first_not_of(" \t");
+			const std::size_t last = value.find_last_not_of(" \t");
+			request.headers[key] = first == std::string::npos ? std::string() : value.substr(first, last - first + 1);
+		}
+
+		if (lineEnd == std::string::npos || lineEnd >= headersEnd)
+			break;
+		lineStart = lineEnd + 2;
+	}
+
+	request.body = bodySeparator == std::string::npos ? std::string() : rawRequest.substr(bodySeparator + 4);
+	return !request.method.empty() && !request.path.empty();
+}
+}

apps/RenderCadenceCompositor/control/HttpControlServer.h

@@ -0,0 +1,134 @@
+#pragma once
+
+#include "ControlActionResult.h"
+
+#include <winsock2.h>
+
+#include <atomic>
+#include <chrono>
+#include <filesystem>
+#include <functional>
+#include <map>
+#include <mutex>
+#include <string>
+#include <thread>
+#include <vector>
+
+namespace RenderCadenceCompositor
+{
+struct HttpControlServerConfig
+{
+	unsigned short preferredPort = 8080;
+	unsigned short portSearchCount = 20;
+	std::chrono::milliseconds idleSleep = std::chrono::milliseconds(10);
+};
+
+struct HttpControlServerCallbacks
+{
+	std::function<std::string()> getStateJson;
+	std::function<ControlActionResult(const std::string&)> addLayer;
+	std::function<ControlActionResult(const std::string&)> removeLayer;
+};
+
+class UniqueSocket
+{
+public:
+	explicit UniqueSocket(SOCKET socket = INVALID_SOCKET);
+	~UniqueSocket();
+
+	UniqueSocket(const UniqueSocket&) = delete;
+	UniqueSocket& operator=(const UniqueSocket&) = delete;
+
+	UniqueSocket(UniqueSocket&& other) noexcept;
+	UniqueSocket& operator=(UniqueSocket&& other) noexcept;
+
+	SOCKET get() const { return mSocket; }
+	bool valid() const { return mSocket != INVALID_SOCKET; }
+	SOCKET release();
+	void reset(SOCKET socket = INVALID_SOCKET);
+
+private:
+	SOCKET mSocket = INVALID_SOCKET;
+};
+
+class HttpControlServer
+{
+public:
+	struct HttpRequest
+	{
+		std::string method;
+		std::string path;
+		std::map<std::string, std::string> headers;
+		std::string body;
+	};
+
+	struct HttpResponse
+	{
+		std::string status;
+		std::string contentType;
+		std::string body;
+	};
+
+	HttpControlServer() = default;
+	~HttpControlServer();
+
+	HttpControlServer(const HttpControlServer&) = delete;
+	HttpControlServer& operator=(const HttpControlServer&) = delete;
+
+	bool Start(
+		const std::filesystem::path& uiRoot,
+		const std::filesystem::path& docsRoot,
+		HttpControlServerConfig config,
+		HttpControlServerCallbacks callbacks,
+		std::string& error);
+	void Stop();
+
+	bool IsRunning() const { return mRunning.load(std::memory_order_acquire); }
+	unsigned short Port() const { return mPort; }
+
+	void SetCallbacksForTest(HttpControlServerCallbacks callbacks);
+	void SetRootsForTest(const std::filesystem::path& uiRoot, const std::filesystem::path& docsRoot);
+	HttpResponse RouteRequestForTest(const HttpRequest& request) const;
+
+	static bool ParseHttpRequest(const std::string& rawRequest, HttpRequest& request);
+	static std::string WebSocketAcceptKey(const std::string& clientKey);
+
+private:
+	void ThreadMain();
+	bool TryAcceptClient();
+	bool HandleClient(UniqueSocket clientSocket);
+	bool HandleWebSocketClient(UniqueSocket clientSocket, const HttpRequest& request);
+	void WebSocketClientMain(UniqueSocket clientSocket);
+	void JoinFinishedClientThreads();
+	bool SendResponse(SOCKET clientSocket, const HttpResponse& response) const;
+	HttpResponse RouteRequest(const HttpRequest& request) const;
+	HttpResponse ServeGet(const HttpRequest& request) const;
+	HttpResponse ServePost(const HttpRequest& request) const;
+	HttpResponse ServeOpenApiSpec() const;
+	HttpResponse ServeSwaggerDocs() const;
+	HttpResponse ServeUiAsset(const std::string& relativePath) const;
+	std::string LoadTextFile(const std::filesystem::path& path) const;
+
+	static HttpResponse JsonResponse(const std::string& status, const std::string& body);
+	static HttpResponse TextResponse(const std::string& status, const std::string& body);
+	static HttpResponse HtmlResponse(const std::string& status, const std::string& body);
+	static std::string ActionResponse(bool ok, const std::string& error = std::string());
+	static bool SendWebSocketText(SOCKET clientSocket, const std::string& text);
+	static std::string GuessContentType(const std::filesystem::path& path);
+	static bool IsSafeRelativePath(const std::filesystem::path& path);
+	static std::string ToLower(std::string text);
+
+	std::filesystem::path mUiRoot;
+	std::filesystem::path mDocsRoot;
+	HttpControlServerConfig mConfig;
+	HttpControlServerCallbacks mCallbacks;
+	UniqueSocket mListenSocket;
+	std::thread mThread;
+	std::mutex mClientThreadsMutex;
+	std::vector<std::thread> mClientThreads;
+	std::vector<std::thread> mFinishedClientThreads;
+	std::atomic<bool> mRunning{ false };
+	unsigned short mPort = 0;
+	bool mWinsockStarted = false;
+};
+}

apps/RenderCadenceCompositor/control/RuntimeStateJson.h

@@ -0,0 +1,296 @@
+#pragma once
+
+#include "../app/AppConfig.h"
+#include "../app/AppConfigProvider.h"
+#include "../json/JsonWriter.h"
+#include "../runtime/RuntimeLayerModel.h"
+#include "../runtime/SupportedShaderCatalog.h"
+#include "../telemetry/CadenceTelemetryJson.h"
+
+#include <cstdint>
+#include <string>
+#include <vector>
+
+namespace RenderCadenceCompositor
+{
+struct RuntimeStateJsonInput
+{
+	const AppConfig& config;
+	const CadenceTelemetrySnapshot& telemetry;
+	unsigned short serverPort = 0;
+	bool videoOutputEnabled = false;
+	std::string videoOutputStatus;
+	const SupportedShaderCatalog& shaderCatalog;
+	const RuntimeLayerModelSnapshot& runtimeLayers;
+};
+
+inline void WriteVideoIoStatusJson(JsonWriter& writer, const RuntimeStateJsonInput& input)
+{
+	writer.BeginObject();
+	writer.KeyString("backend", "decklink");
+	writer.KeyNull("modelName");
+	writer.KeyBool("supportsInternalKeying", false);
+	writer.KeyBool("supportsExternalKeying", false);
+	writer.KeyBool("keyerInterfaceAvailable", false);
+	writer.KeyBool("externalKeyingRequested", input.config.deckLink.externalKeyingEnabled);
+	writer.KeyBool("externalKeyingActive", input.videoOutputEnabled && input.config.deckLink.externalKeyingEnabled);
+	writer.KeyString("statusMessage", input.videoOutputStatus);
+	writer.EndObject();
+}
+
+inline void OutputDimensions(const RuntimeStateJsonInput& input, unsigned& width, unsigned& height)
+{
+	VideoFormatDimensions(input.config.outputVideoFormat, width, height);
+}
+
+inline const char* ShaderParameterTypeName(ShaderParameterType type)
+{
+	switch (type)
+	{
+	case ShaderParameterType::Float: return "float";
+	case ShaderParameterType::Vec2: return "vec2";
+	case ShaderParameterType::Color: return "color";
+	case ShaderParameterType::Boolean: return "bool";
+	case ShaderParameterType::Enum: return "enum";
+	case ShaderParameterType::Text: return "text";
+	case ShaderParameterType::Trigger: return "trigger";
+	}
+	return "unknown";
+}
+
+inline void WriteNumberArray(JsonWriter& writer, const std::vector<double>& values)
+{
+	writer.BeginArray();
+	for (double value : values)
+		writer.Double(value);
+	writer.EndArray();
+}
+
+inline void WriteDefaultParameterValue(JsonWriter& writer, const ShaderParameterDefinition& parameter)
+{
+	switch (parameter.type)
+	{
+	case ShaderParameterType::Boolean:
+		writer.Bool(parameter.defaultBoolean);
+		return;
+	case ShaderParameterType::Enum:
+		writer.String(parameter.defaultEnumValue);
+		return;
+	case ShaderParameterType::Text:
+		writer.String(parameter.defaultTextValue);
+		return;
+	case ShaderParameterType::Trigger:
+		writer.Double(0.0);
+		return;
+	case ShaderParameterType::Float:
+		writer.Double(parameter.defaultNumbers.empty() ? 0.0 : parameter.defaultNumbers.front());
+		return;
+	case ShaderParameterType::Vec2:
+	case ShaderParameterType::Color:
+		WriteNumberArray(writer, parameter.defaultNumbers);
+		return;
+	}
+	writer.Null();
+}
+
+inline void WriteTemporalJson(JsonWriter& writer, const TemporalSettings& temporal)
+{
+	writer.BeginObject();
+	writer.KeyBool("enabled", temporal.enabled);
+	writer.KeyString("historySource", "none");
+	writer.KeyUInt("requestedHistoryLength", temporal.requestedHistoryLength);
+	writer.KeyUInt("effectiveHistoryLength", temporal.effectiveHistoryLength);
+	writer.EndObject();
+}
+
+inline void WriteFeedbackJson(JsonWriter& writer, const FeedbackSettings& feedback)
+{
+	writer.BeginObject();
+	writer.KeyBool("enabled", feedback.enabled);
+	writer.KeyString("writePass", feedback.writePassId);
+	writer.EndObject();
+}
+
+inline const char* RuntimeLayerBuildStateName(RuntimeLayerBuildState state)
+{
+	switch (state)
+	{
+	case RuntimeLayerBuildState::Pending: return "pending";
+	case RuntimeLayerBuildState::Ready: return "ready";
+	case RuntimeLayerBuildState::Failed: return "failed";
+	}
+	return "unknown";
+}
+
+inline void WriteParameterDefinitionJson(JsonWriter& writer, const ShaderParameterDefinition& parameter)
+{
+	writer.BeginObject();
+	writer.KeyString("id", parameter.id);
+	writer.KeyString("label", parameter.label.empty() ? parameter.id : parameter.label);
+	writer.KeyString("description", parameter.description);
+	writer.KeyString("type", ShaderParameterTypeName(parameter.type));
+	writer.Key("defaultValue");
+	WriteDefaultParameterValue(writer, parameter);
+	writer.Key("value");
+	WriteDefaultParameterValue(writer, parameter);
+
+	if (!parameter.minNumbers.empty())
+	{
+		writer.Key("min");
+		WriteNumberArray(writer, parameter.minNumbers);
+	}
+	if (!parameter.maxNumbers.empty())
+	{
+		writer.Key("max");
+		WriteNumberArray(writer, parameter.maxNumbers);
+	}
+	if (!parameter.stepNumbers.empty())
+	{
+		writer.Key("step");
+		WriteNumberArray(writer, parameter.stepNumbers);
+	}
+	if (parameter.type == ShaderParameterType::Enum)
+	{
+		writer.Key("options");
+		writer.BeginArray();
+		for (const ShaderParameterOption& option : parameter.enumOptions)
+		{
+			writer.BeginObject();
+			writer.KeyString("value", option.value);
+			writer.KeyString("label", option.label.empty() ? option.value : option.label);
+			writer.EndObject();
+		}
+		writer.EndArray();
+	}
+	if (parameter.type == ShaderParameterType::Text)
+	{
+		writer.KeyUInt("maxLength", parameter.maxLength);
+		if (!parameter.fontId.empty())
+			writer.KeyString("font", parameter.fontId);
+	}
+	writer.EndObject();
+}
+
+inline void WriteLayersJson(JsonWriter& writer, const RuntimeStateJsonInput& input)
+{
+	writer.BeginArray();
+	for (const RuntimeLayerReadModel& layer : input.runtimeLayers.displayLayers)
+	{
+		const ShaderPackage* shaderPackage = input.shaderCatalog.FindPackage(layer.shaderId);
+		writer.BeginObject();
+		writer.KeyString("id", layer.id);
+		writer.KeyString("shaderId", layer.shaderId);
+		writer.KeyString("shaderName", layer.shaderName);
+		writer.KeyBool("bypass", layer.bypass);
+		writer.KeyString("buildState", RuntimeLayerBuildStateName(layer.buildState));
+		writer.KeyBool("renderReady", layer.renderReady);
+		writer.KeyString("message", layer.message);
+		writer.Key("temporal");
+		if (shaderPackage)
+			WriteTemporalJson(writer, shaderPackage->temporal);
+		else
+			WriteTemporalJson(writer, TemporalSettings());
+		writer.Key("feedback");
+		if (shaderPackage)
+			WriteFeedbackJson(writer, shaderPackage->feedback);
+		else
+			WriteFeedbackJson(writer, FeedbackSettings());
+		writer.Key("parameters");
+		writer.BeginArray();
+		if (shaderPackage)
+		{
+			for (const ShaderParameterDefinition& parameter : shaderPackage->parameters)
+				WriteParameterDefinitionJson(writer, parameter);
+		}
+		writer.EndArray();
+		writer.EndObject();
+	}
+	writer.EndArray();
+}
+
+inline std::string RuntimeStateToJson(const RuntimeStateJsonInput& input)
+{
+	JsonWriter writer;
+	writer.BeginObject();
+
+	writer.Key("app");
+	writer.BeginObject();
+	writer.KeyUInt("serverPort", input.serverPort);
+	writer.KeyUInt("oscPort", input.config.oscPort);
+	writer.KeyString("oscBindAddress", input.config.oscBindAddress);
+	writer.KeyDouble("oscSmoothing", input.config.oscSmoothing);
+	writer.KeyBool("autoReload", input.config.autoReload);
+	writer.KeyUInt("maxTemporalHistoryFrames", static_cast<uint64_t>(input.config.maxTemporalHistoryFrames));
+	writer.KeyDouble("previewFps", input.config.previewFps);
+	writer.KeyBool("enableExternalKeying", input.config.deckLink.externalKeyingEnabled);
+	writer.KeyString("inputVideoFormat", input.config.inputVideoFormat);
+	writer.KeyString("inputFrameRate", input.config.inputFrameRate);
+	writer.KeyString("outputVideoFormat", input.config.outputVideoFormat);
+	writer.KeyString("outputFrameRate", input.config.outputFrameRate);
+	writer.EndObject();
+
+	writer.Key("runtime");
+	writer.BeginObject();
+	writer.KeyUInt("layerCount", static_cast<uint64_t>(input.runtimeLayers.displayLayers.size()));
+	writer.KeyBool("compileSucceeded", input.runtimeLayers.compileSucceeded);
+	writer.KeyString("compileMessage", input.runtimeLayers.compileMessage);
+	writer.EndObject();
+
+	writer.Key("video");
+	writer.BeginObject();
+	unsigned outputWidth = 0;
+	unsigned outputHeight = 0;
+	OutputDimensions(input, outputWidth, outputHeight);
+	writer.KeyBool("hasSignal", input.videoOutputEnabled);
+	writer.KeyUInt("width", outputWidth);
+	writer.KeyUInt("height", outputHeight);
+	writer.KeyString("modeName", input.config.outputVideoFormat + " output-only");
+	writer.EndObject();
+
+	writer.Key("decklink");
+	WriteVideoIoStatusJson(writer, input);
+	writer.Key("videoIO");
+	WriteVideoIoStatusJson(writer, input);
+
+	writer.Key("performance");
+	writer.BeginObject();
+	writer.KeyDouble("frameBudgetMs", FrameDurationMillisecondsFromRateString(input.config.outputFrameRate));
+	writer.KeyNull("renderMs");
+	writer.KeyNull("smoothedRenderMs");
+	writer.KeyNull("budgetUsedPercent");
+	writer.KeyNull("completionIntervalMs");
+	writer.KeyNull("smoothedCompletionIntervalMs");
+	writer.KeyNull("maxCompletionIntervalMs");
+	writer.KeyUInt("lateFrameCount", input.telemetry.displayedLate);
+	writer.KeyUInt("droppedFrameCount", input.telemetry.dropped);
+	writer.KeyNull("flushedFrameCount");
+	writer.Key("cadence");
+	WriteCadenceTelemetryJson(writer, input.telemetry);
+	writer.EndObject();
+
+	writer.KeyNull("backendPlayout");
+	writer.KeyNull("runtimeEvents");
+	writer.Key("shaders");
+	writer.BeginArray();
+	for (const SupportedShaderSummary& shader : input.shaderCatalog.Shaders())
+	{
+		writer.BeginObject();
+		writer.KeyString("id", shader.id);
+		writer.KeyString("name", shader.name);
+		writer.KeyString("description", shader.description);
+		writer.KeyString("category", shader.category);
+		writer.KeyBool("available", true);
+		writer.KeyNull("error");
+		writer.EndObject();
+	}
+	writer.EndArray();
+	writer.Key("stackPresets");
+	writer.BeginArray();
+	writer.EndArray();
+	writer.Key("layers");
+	WriteLayersJson(writer, input);
+
+	writer.EndObject();
+	return writer.StringValue();
+}
+}

apps/RenderCadenceCompositor/frames/SystemFrameExchange.cpp

@@ -0,0 +1,245 @@
+#include "SystemFrameExchange.h"
+
+namespace
+{
+SystemFrameExchangeConfig NormalizeConfig(SystemFrameExchangeConfig config)
+{
+	if (config.rowBytes == 0)
+		config.rowBytes = VideoIORowBytes(config.pixelFormat, config.width);
+	return config;
+}
+}
+
+SystemFrameExchange::SystemFrameExchange(const SystemFrameExchangeConfig& config)
+{
+	Configure(config);
+}
+
+void SystemFrameExchange::Configure(const SystemFrameExchangeConfig& config)
+{
+	std::lock_guard<std::mutex> lock(mMutex);
+	mConfig = NormalizeConfig(config);
+	mCompletedIndices.clear();
+	mSlots.clear();
+	mSlots.resize(mConfig.capacity);
+
+	const std::size_t byteCount = FrameByteCount();
+	for (Slot& slot : mSlots)
+	{
+		slot.bytes.resize(byteCount);
+		slot.state = SystemFrameSlotState::Free;
+		slot.frameIndex = 0;
+		++slot.generation;
+	}
+
+	mCounters = SystemFrameExchangeMetrics();
+	mCondition.notify_all();
+}
+
+SystemFrameExchangeConfig SystemFrameExchange::Config() const
+{
+	std::lock_guard<std::mutex> lock(mMutex);
+	return mConfig;
+}
+
+bool SystemFrameExchange::AcquireForRender(SystemFrame& frame)
+{
+	std::lock_guard<std::mutex> lock(mMutex);
+	if (!AcquireFreeLocked(frame))
+	{
+		if (!DropOldestCompletedLocked() || !AcquireFreeLocked(frame))
+		{
+			frame = SystemFrame();
+			++mCounters.acquireMisses;
+			return false;
+		}
+	}
+
+	++mCounters.acquiredFrames;
+	return true;
+}
+
+bool SystemFrameExchange::PublishCompleted(const SystemFrame& frame)
+{
+	std::lock_guard<std::mutex> lock(mMutex);
+	if (!IsValidLocked(frame))
+		return false;
+
+	Slot& slot = mSlots[frame.index];
+	if (slot.state != SystemFrameSlotState::Rendering)
+		return false;
+
+	slot.state = SystemFrameSlotState::Completed;
+	slot.frameIndex = frame.frameIndex;
+	mCompletedIndices.push_back(frame.index);
+	++mCounters.completedFrames;
+	mCondition.notify_all();
+	return true;
+}
+
+bool SystemFrameExchange::ConsumeCompletedForSchedule(SystemFrame& frame)
+{
+	std::lock_guard<std::mutex> lock(mMutex);
+	while (!mCompletedIndices.empty())
+	{
+		const std::size_t index = mCompletedIndices.front();
+		mCompletedIndices.pop_front();
+		if (index >= mSlots.size() || mSlots[index].state != SystemFrameSlotState::Completed)
+			continue;
+
+		mSlots[index].state = SystemFrameSlotState::Scheduled;
+		FillFrameLocked(index, frame);
+		++mCounters.scheduledFrames;
+		return true;
+	}
+
+	frame = SystemFrame();
+	++mCounters.completedPollMisses;
+	return false;
+}
+
+bool SystemFrameExchange::ReleaseScheduledByBytes(void* bytes)
+{
+	if (bytes == nullptr)
+		return false;
+
+	std::lock_guard<std::mutex> lock(mMutex);
+	for (std::size_t index = 0; index < mSlots.size(); ++index)
+	{
+		Slot& slot = mSlots[index];
+		if (slot.bytes.empty() || slot.bytes.data() != bytes)
+			continue;
+		if (slot.state != SystemFrameSlotState::Scheduled)
+			return false;
+
+		slot.state = SystemFrameSlotState::Free;
+		slot.frameIndex = 0;
+		++slot.generation;
+		mCondition.notify_all();
+		return true;
+	}
+
+	return false;
+}
+
+bool SystemFrameExchange::WaitForCompletedDepth(std::size_t targetDepth, std::chrono::milliseconds timeout)
+{
+	std::unique_lock<std::mutex> lock(mMutex);
+	return mCondition.wait_for(lock, timeout, [&]() {
+		return CompletedCountLocked() >= targetDepth;
+	});
+}
+
+void SystemFrameExchange::Clear()
+{
+	std::lock_guard<std::mutex> lock(mMutex);
+	mCompletedIndices.clear();
+	for (Slot& slot : mSlots)
+	{
+		slot.state = SystemFrameSlotState::Free;
+		slot.frameIndex = 0;
+		++slot.generation;
+	}
+	mCondition.notify_all();
+}
+
+SystemFrameExchangeMetrics SystemFrameExchange::Metrics() const
+{
+	std::lock_guard<std::mutex> lock(mMutex);
+	SystemFrameExchangeMetrics metrics = mCounters;
+	metrics.capacity = mSlots.size();
+	metrics.completedDepth = mCompletedIndices.size();
+
+	for (const Slot& slot : mSlots)
+	{
+		switch (slot.state)
+		{
+		case SystemFrameSlotState::Free:
+			++metrics.freeCount;
+			break;
+		case SystemFrameSlotState::Rendering:
+			++metrics.renderingCount;
+			break;
+		case SystemFrameSlotState::Completed:
+			++metrics.completedCount;
+			break;
+		case SystemFrameSlotState::Scheduled:
+			++metrics.scheduledCount;
+			break;
+		}
+	}
+
+	return metrics;
+}
+
+bool SystemFrameExchange::AcquireFreeLocked(SystemFrame& frame)
+{
+	for (std::size_t index = 0; index < mSlots.size(); ++index)
+	{
+		Slot& slot = mSlots[index];
+		if (slot.state != SystemFrameSlotState::Free)
+			continue;
+
+		slot.state = SystemFrameSlotState::Rendering;
+		++slot.generation;
+		FillFrameLocked(index, frame);
+		return true;
+	}
+
+	return false;
+}
+
+bool SystemFrameExchange::DropOldestCompletedLocked()
+{
+	while (!mCompletedIndices.empty())
+	{
+		const std::size_t index = mCompletedIndices.front();
+		mCompletedIndices.pop_front();
+		if (index >= mSlots.size() || mSlots[index].state != SystemFrameSlotState::Completed)
+			continue;
+
+		Slot& slot = mSlots[index];
+		slot.state = SystemFrameSlotState::Free;
+		slot.frameIndex = 0;
+		++slot.generation;
+		++mCounters.completedDrops;
+		mCondition.notify_all();
+		return true;
+	}
+
+	return false;
+}
+
+bool SystemFrameExchange::IsValidLocked(const SystemFrame& frame) const
+{
+	return frame.index < mSlots.size() && mSlots[frame.index].generation == frame.generation;
+}
+
+void SystemFrameExchange::FillFrameLocked(std::size_t index, SystemFrame& frame)
+{
+	Slot& slot = mSlots[index];
+	frame.bytes = slot.bytes.empty() ? nullptr : slot.bytes.data();
+	frame.rowBytes = static_cast<long>(mConfig.rowBytes);
+	frame.width = mConfig.width;
+	frame.height = mConfig.height;
+	frame.pixelFormat = mConfig.pixelFormat;
+	frame.index = index;
+	frame.generation = slot.generation;
+	frame.frameIndex = slot.frameIndex;
+}
+
+std::size_t SystemFrameExchange::CompletedCountLocked() const
+{
+	std::size_t count = 0;
+	for (const Slot& slot : mSlots)
+	{
+		if (slot.state == SystemFrameSlotState::Completed)
+			++count;
+	}
+	return count;
+}
+
+std::size_t SystemFrameExchange::FrameByteCount() const
+{
+	return static_cast<std::size_t>(mConfig.rowBytes) * static_cast<std::size_t>(mConfig.height);
+}

apps/RenderCadenceCompositor/frames/SystemFrameExchange.h

@@ -0,0 +1,51 @@
+#pragma once
+
+#include "SystemFrameTypes.h"
+
+#include <chrono>
+#include <condition_variable>
+#include <deque>
+#include <mutex>
+#include <vector>
+
+class SystemFrameExchange
+{
+public:
+	SystemFrameExchange() = default;
+	explicit SystemFrameExchange(const SystemFrameExchangeConfig& config);
+
+	void Configure(const SystemFrameExchangeConfig& config);
+	SystemFrameExchangeConfig Config() const;
+
+	bool AcquireForRender(SystemFrame& frame);
+	bool PublishCompleted(const SystemFrame& frame);
+	bool ConsumeCompletedForSchedule(SystemFrame& frame);
+	bool ReleaseScheduledByBytes(void* bytes);
+	bool WaitForCompletedDepth(std::size_t targetDepth, std::chrono::milliseconds timeout);
+	void Clear();
+
+	SystemFrameExchangeMetrics Metrics() const;
+
+private:
+	struct Slot
+	{
+		std::vector<unsigned char> bytes;
+		SystemFrameSlotState state = SystemFrameSlotState::Free;
+		uint64_t generation = 1;
+		uint64_t frameIndex = 0;
+	};
+
+	bool AcquireFreeLocked(SystemFrame& frame);
+	bool DropOldestCompletedLocked();
+	bool IsValidLocked(const SystemFrame& frame) const;
+	void FillFrameLocked(std::size_t index, SystemFrame& frame);
+	std::size_t CompletedCountLocked() const;
+	std::size_t FrameByteCount() const;
+
+	mutable std::mutex mMutex;
+	std::condition_variable mCondition;
+	SystemFrameExchangeConfig mConfig;
+	std::vector<Slot> mSlots;
+	std::deque<std::size_t> mCompletedIndices;
+	SystemFrameExchangeMetrics mCounters;
+};

apps/RenderCadenceCompositor/frames/SystemFrameTypes.h

@@ -0,0 +1,51 @@
+#pragma once
+
+#include "VideoIOFormat.h"
+
+#include <cstddef>
+#include <cstdint>
+
+enum class SystemFrameSlotState
+{
+	Free,
+	Rendering,
+	Completed,
+	Scheduled
+};
+
+struct SystemFrameExchangeConfig
+{
+	unsigned width = 0;
+	unsigned height = 0;
+	VideoIOPixelFormat pixelFormat = VideoIOPixelFormat::Bgra8;
+	unsigned rowBytes = 0;
+	std::size_t capacity = 0;
+};
+
+struct SystemFrame
+{
+	void* bytes = nullptr;
+	long rowBytes = 0;
+	unsigned width = 0;
+	unsigned height = 0;
+	VideoIOPixelFormat pixelFormat = VideoIOPixelFormat::Bgra8;
+	std::size_t index = 0;
+	uint64_t generation = 0;
+	uint64_t frameIndex = 0;
+};
+
+struct SystemFrameExchangeMetrics
+{
+	std::size_t capacity = 0;
+	std::size_t freeCount = 0;
+	std::size_t renderingCount = 0;
+	std::size_t completedCount = 0;
+	std::size_t scheduledCount = 0;
+	std::size_t completedDepth = 0;
+	uint64_t acquiredFrames = 0;
+	uint64_t completedFrames = 0;
+	uint64_t scheduledFrames = 0;
+	uint64_t completedDrops = 0;
+	uint64_t acquireMisses = 0;
+	uint64_t completedPollMisses = 0;
+};

apps/RenderCadenceCompositor/json/JsonWriter.cpp

@@ -0,0 +1,235 @@
+#include "JsonWriter.h"
+
+#include <iomanip>
+#include <stdexcept>
+
+namespace RenderCadenceCompositor
+{
+namespace
+{
+constexpr int kMaxDepth = 32;
+
+void AppendHexEscape(std::ostringstream& stream, unsigned char value)
+{
+	stream << "\\u"
+		<< std::hex << std::uppercase << std::setw(4) << std::setfill('0')
+		<< static_cast<int>(value)
+		<< std::dec << std::nouppercase << std::setfill(' ');
+}
+}
+
+void JsonWriter::BeginObject()
+{
+	BeginValue();
+	mStream << "{";
+	PushScope(ScopeKind::Object);
+}
+
+void JsonWriter::EndObject()
+{
+	PopScope(ScopeKind::Object);
+	mStream << "}";
+}
+
+void JsonWriter::BeginArray()
+{
+	BeginValue();
+	mStream << "[";
+	PushScope(ScopeKind::Array);
+}
+
+void JsonWriter::EndArray()
+{
+	PopScope(ScopeKind::Array);
+	mStream << "]";
+}
+
+void JsonWriter::Key(const std::string& name)
+{
+	BeginKey();
+	mStream << "\"" << EscapeString(name) << "\":";
+}
+
+void JsonWriter::String(const std::string& value)
+{
+	BeginValue();
+	mStream << "\"" << EscapeString(value) << "\"";
+}
+
+void JsonWriter::Bool(bool value)
+{
+	BeginValue();
+	mStream << (value ? "true" : "false");
+}
+
+void JsonWriter::Null()
+{
+	BeginValue();
+	mStream << "null";
+}
+
+void JsonWriter::Int(int64_t value)
+{
+	BeginValue();
+	mStream << value;
+}
+
+void JsonWriter::UInt(uint64_t value)
+{
+	BeginValue();
+	mStream << value;
+}
+
+void JsonWriter::Double(double value)
+{
+	BeginValue();
+	mStream << std::setprecision(15) << value;
+}
+
+void JsonWriter::KeyString(const std::string& name, const std::string& value)
+{
+	Key(name);
+	String(value);
+}
+
+void JsonWriter::KeyBool(const std::string& name, bool value)
+{
+	Key(name);
+	Bool(value);
+}
+
+void JsonWriter::KeyNull(const std::string& name)
+{
+	Key(name);
+	Null();
+}
+
+void JsonWriter::KeyInt(const std::string& name, int64_t value)
+{
+	Key(name);
+	Int(value);
+}
+
+void JsonWriter::KeyUInt(const std::string& name, uint64_t value)
+{
+	Key(name);
+	UInt(value);
+}
+
+void JsonWriter::KeyDouble(const std::string& name, double value)
+{
+	Key(name);
+	Double(value);
+}
+
+std::string JsonWriter::StringValue() const
+{
+	if (mScopeDepth != 0)
+		throw std::logic_error("JSON document has unclosed scopes.");
+	return mStream.str();
+}
+
+void JsonWriter::Reset()
+{
+	mStream.str(std::string());
+	mStream.clear();
+	mScopeDepth = 0;
+}
+
+std::string JsonWriter::EscapeString(const std::string& value)
+{
+	std::ostringstream stream;
+	for (unsigned char character : value)
+	{
+		switch (character)
+		{
+		case '"':
+			stream << "\\\"";
+			break;
+		case '\\':
+			stream << "\\\\";
+			break;
+		case '\b':
+			stream << "\\b";
+			break;
+		case '\f':
+			stream << "\\f";
+			break;
+		case '\n':
+			stream << "\\n";
+			break;
+		case '\r':
+			stream << "\\r";
+			break;
+		case '\t':
+			stream << "\\t";
+			break;
+		default:
+			if (character < 0x20)
+				AppendHexEscape(stream, character);
+			else
+				stream << character;
+			break;
+		}
+	}
+	return stream.str();
+}
+
+void JsonWriter::BeginValue()
+{
+	if (mScopeDepth == 0)
+		return;
+
+	Scope& scope = mScopes[mScopeDepth - 1];
+	if (scope.kind == ScopeKind::Object)
+	{
+		if (!scope.expectingValue)
+			throw std::logic_error("JSON object value must follow a key.");
+		scope.expectingValue = false;
+		return;
+	}
+
+	if (!scope.first)
+		mStream << ",";
+	scope.first = false;
+}
+
+void JsonWriter::BeginKey()
+{
+	if (mScopeDepth == 0)
+		throw std::logic_error("JSON key cannot be written outside an object.");
+
+	Scope& scope = mScopes[mScopeDepth - 1];
+	if (scope.kind != ScopeKind::Object)
+		throw std::logic_error("JSON key cannot be written inside an array.");
+	if (scope.expectingValue)
+		throw std::logic_error("JSON object key cannot be written before its previous value.");
+
+	if (!scope.first)
+		mStream << ",";
+	scope.first = false;
+	scope.expectingValue = true;
+}
+
+void JsonWriter::PushScope(ScopeKind kind)
+{
+	if (mScopeDepth >= kMaxDepth)
+		throw std::logic_error("JSON nesting is too deep.");
+
+	mScopes[mScopeDepth++] = Scope{ kind, true, false };
+}
+
+void JsonWriter::PopScope(ScopeKind kind)
+{
+	if (mScopeDepth == 0)
+		throw std::logic_error("JSON scope underflow.");
+
+	Scope& scope = mScopes[mScopeDepth - 1];
+	if (scope.kind != kind)
+		throw std::logic_error("JSON scope kind mismatch.");
+	if (scope.expectingValue)
+		throw std::logic_error("JSON object key is missing a value.");
+
+	--mScopeDepth;
+}
+}

apps/RenderCadenceCompositor/json/JsonWriter.h

@@ -0,0 +1,60 @@
+#pragma once
+
+#include <cstdint>
+#include <sstream>
+#include <string>
+
+namespace RenderCadenceCompositor
+{
+class JsonWriter
+{
+public:
+	void BeginObject();
+	void EndObject();
+	void BeginArray();
+	void EndArray();
+
+	void Key(const std::string& name);
+	void String(const std::string& value);
+	void Bool(bool value);
+	void Null();
+	void Int(int64_t value);
+	void UInt(uint64_t value);
+	void Double(double value);
+
+	void KeyString(const std::string& name, const std::string& value);
+	void KeyBool(const std::string& name, bool value);
+	void KeyNull(const std::string& name);
+	void KeyInt(const std::string& name, int64_t value);
+	void KeyUInt(const std::string& name, uint64_t value);
+	void KeyDouble(const std::string& name, double value);
+
+	std::string StringValue() const;
+	void Reset();
+
+	static std::string EscapeString(const std::string& value);
+
+private:
+	enum class ScopeKind
+	{
+		Object,
+		Array
+	};
+
+	struct Scope
+	{
+		ScopeKind kind = ScopeKind::Object;
+		bool first = true;
+		bool expectingValue = false;
+	};
+
+	void BeginValue();
+	void BeginKey();
+	void PushScope(ScopeKind kind);
+	void PopScope(ScopeKind kind);
+
+	std::ostringstream mStream;
+	Scope mScopes[32];
+	int mScopeDepth = 0;
+};
+}

apps/RenderCadenceCompositor/logging/Logger.cpp

@@ -0,0 +1,283 @@
+#include "Logger.h"
+
+#include <windows.h>
+
+#include <iomanip>
+#include <iostream>
+#include <sstream>
+#include <ctime>
+#include <filesystem>
+
+namespace RenderCadenceCompositor
+{
+namespace
+{
+int Rank(LogLevel level)
+{
+	switch (level)
+	{
+	case LogLevel::Log:
+		return 0;
+	case LogLevel::Warning:
+		return 1;
+	case LogLevel::Error:
+		return 2;
+	default:
+		return 0;
+	}
+}
+
+std::string FormatTimestamp(std::chrono::system_clock::time_point timestamp)
+{
+	const std::time_t time = std::chrono::system_clock::to_time_t(timestamp);
+	std::tm localTime = {};
+	localtime_s(&localTime, &time);
+
+	std::ostringstream stream;
+	stream << std::put_time(&localTime, "%Y-%m-%d %H:%M:%S");
+	return stream.str();
+}
+
+std::string FormatRecord(const Logger::Record& record)
+{
+	std::ostringstream stream;
+	stream << FormatTimestamp(record.timestamp)
+		<< " [" << LogLevelName(record.level) << "]"
+		<< " [" << record.subsystem << "] "
+		<< record.message;
+	return stream.str();
+}
+}
+
+const char* LogLevelName(LogLevel level)
+{
+	switch (level)
+	{
+	case LogLevel::Log:
+		return "log";
+	case LogLevel::Warning:
+		return "warning";
+	case LogLevel::Error:
+		return "error";
+	default:
+		return "log";
+	}
+}
+
+Logger& Logger::Instance()
+{
+	static Logger logger;
+	return logger;
+}
+
+Logger::~Logger()
+{
+	Stop();
+}
+
+void Logger::Start(LoggerConfig config)
+{
+	std::lock_guard<std::mutex> lock(mMutex);
+	if (mRunning)
+		return;
+
+	mConfig = config;
+	mStopping = false;
+	mRunning = true;
+	OpenFileSink();
+	{
+		std::lock_guard<std::mutex> countersLock(mCountersMutex);
+		mCounters = LoggerCounters();
+	}
+	mThread = std::thread([this]() { ThreadMain(); });
+}
+
+void Logger::Stop()
+{
+	{
+		std::lock_guard<std::mutex> lock(mMutex);
+		if (!mRunning && !mThread.joinable())
+			return;
+		mStopping = true;
+	}
+	mCondition.notify_all();
+
+	if (mThread.joinable())
+		mThread.join();
+
+	std::lock_guard<std::mutex> lock(mMutex);
+	CloseFileSink();
+	mRunning = false;
+}
+
+void Logger::Write(LogLevel level, const std::string& subsystem, const std::string& message)
+{
+	Enqueue(Record{ std::chrono::system_clock::now(), std::this_thread::get_id(), level, subsystem, message }, true);
+}
+
+bool Logger::TryWrite(LogLevel level, const std::string& subsystem, const std::string& message)
+{
+	return Enqueue(Record{ std::chrono::system_clock::now(), std::this_thread::get_id(), level, subsystem, message }, false);
+}
+
+void Logger::Log(const std::string& subsystem, const std::string& message)
+{
+	Write(LogLevel::Log, subsystem, message);
+}
+
+void Logger::Warning(const std::string& subsystem, const std::string& message)
+{
+	Write(LogLevel::Warning, subsystem, message);
+}
+
+void Logger::Error(const std::string& subsystem, const std::string& message)
+{
+	Write(LogLevel::Error, subsystem, message);
+}
+
+LoggerCounters Logger::Counters() const
+{
+	std::lock_guard<std::mutex> lock(mCountersMutex);
+	return mCounters;
+}
+
+bool Logger::IsRunning() const
+{
+	std::lock_guard<std::mutex> lock(mMutex);
+	return mRunning;
+}
+
+bool Logger::ShouldWrite(LogLevel level) const
+{
+	return Rank(level) >= Rank(mConfig.minimumLevel);
+}
+
+bool Logger::Enqueue(Record record, bool block)
+{
+	if (!ShouldWrite(record.level))
+		return true;
+
+	std::unique_lock<std::mutex> lock(mMutex, std::defer_lock);
+	if (block)
+	{
+		lock.lock();
+	}
+	else if (!lock.try_lock())
+	{
+		std::lock_guard<std::mutex> countersLock(mCountersMutex);
+		++mCounters.dropped;
+		return false;
+	}
+
+	if (!mRunning)
+	{
+		lock.unlock();
+		WriteRecord(record);
+		return true;
+	}
+
+	if (mQueue.size() >= mConfig.maxQueuedMessages)
+	{
+		std::lock_guard<std::mutex> countersLock(mCountersMutex);
+		++mCounters.dropped;
+		return false;
+	}
+
+	mQueue.push_back(std::move(record));
+	{
+		std::lock_guard<std::mutex> countersLock(mCountersMutex);
+		++mCounters.queued;
+	}
+	lock.unlock();
+	mCondition.notify_one();
+	return true;
+}
+
+void Logger::ThreadMain()
+{
+	for (;;)
+	{
+		Record record;
+		{
+			std::unique_lock<std::mutex> lock(mMutex);
+			mCondition.wait(lock, [this]() {
+				return mStopping || !mQueue.empty();
+			});
+
+			if (mQueue.empty())
+			{
+				if (mStopping)
+					return;
+				continue;
+			}
+
+			record = std::move(mQueue.front());
+			mQueue.pop_front();
+		}
+		WriteRecord(record);
+	}
+}
+
+void Logger::WriteRecord(const Record& record)
+{
+	const std::string line = FormatRecord(record);
+
+	if (mConfig.writeToDebugOutput)
+		OutputDebugStringA((line + "\n").c_str());
+
+	if (mConfig.writeToConsole)
+	{
+		if (record.level == LogLevel::Error)
+			std::cerr << line << "\n";
+		else
+			std::cout << line << "\n";
+	}
+	if (mFile.is_open())
+	{
+		mFile << line << "\n";
+		mFile.flush();
+	}
+
+	std::lock_guard<std::mutex> lock(mCountersMutex);
+	++mCounters.written;
+}
+
+void Logger::OpenFileSink()
+{
+	CloseFileSink();
+	if (!mConfig.writeToFile || mConfig.filePath.empty())
+		return;
+
+	std::error_code error;
+	const std::filesystem::path logPath(mConfig.filePath);
+	if (logPath.has_parent_path())
+		std::filesystem::create_directories(logPath.parent_path(), error);
+	mFile.open(logPath, std::ios::out | std::ios::app);
+}
+
+void Logger::CloseFileSink()
+{
+	if (mFile.is_open())
+		mFile.close();
+}
+
+bool TryLog(LogLevel level, const std::string& subsystem, const std::string& message)
+{
+	return Logger::Instance().TryWrite(level, subsystem, message);
+}
+
+void Log(const std::string& subsystem, const std::string& message)
+{
+	Logger::Instance().Log(subsystem, message);
+}
+
+void LogWarning(const std::string& subsystem, const std::string& message)
+{
+	Logger::Instance().Warning(subsystem, message);
+}
+
+void LogError(const std::string& subsystem, const std::string& message)
+{
+	Logger::Instance().Error(subsystem, message);
+}
+}

apps/RenderCadenceCompositor/logging/Logger.h

@@ -0,0 +1,101 @@
+#pragma once
+
+#include <atomic>
+#include <chrono>
+#include <condition_variable>
+#include <cstddef>
+#include <cstdint>
+#include <deque>
+#include <fstream>
+#include <mutex>
+#include <string>
+#include <thread>
+
+namespace RenderCadenceCompositor
+{
+enum class LogLevel
+{
+	Log,
+	Warning,
+	Error
+};
+
+struct LoggerConfig
+{
+	LogLevel minimumLevel = LogLevel::Log;
+	bool writeToConsole = true;
+	bool writeToDebugOutput = true;
+	bool writeToFile = true;
+	std::string filePath = "logs/render-cadence-compositor.log";
+	std::size_t maxQueuedMessages = 1024;
+};
+
+struct LoggerCounters
+{
+	uint64_t queued = 0;
+	uint64_t written = 0;
+	uint64_t dropped = 0;
+};
+
+const char* LogLevelName(LogLevel level);
+
+class Logger
+{
+public:
+	struct Record
+	{
+		std::chrono::system_clock::time_point timestamp;
+		std::thread::id threadId;
+		LogLevel level = LogLevel::Log;
+		std::string subsystem;
+		std::string message;
+	};
+
+	static Logger& Instance();
+
+	Logger(const Logger&) = delete;
+	Logger& operator=(const Logger&) = delete;
+
+	~Logger();
+
+	void Start(LoggerConfig config = LoggerConfig());
+	void Stop();
+
+	void Write(LogLevel level, const std::string& subsystem, const std::string& message);
+	bool TryWrite(LogLevel level, const std::string& subsystem, const std::string& message);
+
+	void Log(const std::string& subsystem, const std::string& message);
+	void Warning(const std::string& subsystem, const std::string& message);
+	void Error(const std::string& subsystem, const std::string& message);
+
+	LoggerCounters Counters() const;
+	bool IsRunning() const;
+
+private:
+	Logger() = default;
+
+	bool ShouldWrite(LogLevel level) const;
+	bool Enqueue(Record record, bool block);
+	void ThreadMain();
+	void WriteRecord(const Record& record);
+	void OpenFileSink();
+	void CloseFileSink();
+
+	LoggerConfig mConfig;
+	std::ofstream mFile;
+	std::thread mThread;
+	mutable std::mutex mMutex;
+	std::condition_variable mCondition;
+	std::deque<Record> mQueue;
+	bool mStopping = false;
+	bool mRunning = false;
+
+	mutable std::mutex mCountersMutex;
+	LoggerCounters mCounters;
+};
+
+bool TryLog(LogLevel level, const std::string& subsystem, const std::string& message);
+void Log(const std::string& subsystem, const std::string& message);
+void LogWarning(const std::string& subsystem, const std::string& message);
+void LogError(const std::string& subsystem, const std::string& message);
+}

apps/RenderCadenceCompositor/platform/HiddenGlWindow.cpp

@@ -0,0 +1,134 @@
+#include "HiddenGlWindow.h"
+
+namespace
+{
+constexpr const char* kWindowClassName = "RenderCadenceCompositorHiddenGlWindow";
+}
+
+HiddenGlWindow::~HiddenGlWindow()
+{
+	Destroy();
+}
+
+bool HiddenGlWindow::Create(unsigned width, unsigned height, std::string& error)
+{
+	return CreateShared(width, height, nullptr, nullptr, error);
+}
+
+bool HiddenGlWindow::CreateShared(unsigned width, unsigned height, HDC sharedDeviceContext, HGLRC sharedContext, std::string& error)
+{
+	Destroy();
+
+	mInstance = GetModuleHandle(nullptr);
+
+	WNDCLASSA wc = {};
+	wc.style = CS_OWNDC;
+	wc.lpfnWndProc = HiddenGlWindow::WindowProc;
+	wc.hInstance = mInstance;
+	wc.lpszClassName = kWindowClassName;
+
+	mClassAtom = RegisterClassA(&wc);
+	if (mClassAtom == 0 && GetLastError() != ERROR_CLASS_ALREADY_EXISTS)
+	{
+		error = "RegisterClassA failed for hidden OpenGL window.";
+		return false;
+	}
+
+	mWindow = CreateWindowA(
+		kWindowClassName,
+		"Render Cadence Compositor Hidden GL",
+		WS_OVERLAPPEDWINDOW,
+		CW_USEDEFAULT,
+		CW_USEDEFAULT,
+		static_cast<int>(width),
+		static_cast<int>(height),
+		nullptr,
+		nullptr,
+		mInstance,
+		nullptr);
+	if (!mWindow)
+	{
+		error = "CreateWindowA failed for hidden OpenGL window.";
+		return false;
+	}
+
+	mDc = GetDC(mWindow);
+	if (!mDc)
+	{
+		error = "GetDC failed for hidden OpenGL window.";
+		return false;
+	}
+
+	PIXELFORMATDESCRIPTOR pfd = {};
+	pfd.nSize = sizeof(pfd);
+	pfd.nVersion = 1;
+	pfd.dwFlags = PFD_DRAW_TO_WINDOW | PFD_SUPPORT_OPENGL | PFD_DOUBLEBUFFER;
+	pfd.iPixelType = PFD_TYPE_RGBA;
+	pfd.cColorBits = 32;
+	pfd.cDepthBits = 0;
+	pfd.iLayerType = PFD_MAIN_PLANE;
+
+	int pixelFormat = 0;
+	if (sharedDeviceContext != nullptr)
+		pixelFormat = GetPixelFormat(sharedDeviceContext);
+	if (pixelFormat == 0)
+		pixelFormat = ChoosePixelFormat(mDc, &pfd);
+	if (pixelFormat == 0 || !SetPixelFormat(mDc, pixelFormat, &pfd))
+	{
+		error = "Could not choose/set pixel format for hidden OpenGL window.";
+		return false;
+	}
+
+	mGlrc = wglCreateContext(mDc);
+	if (!mGlrc)
+	{
+		error = "wglCreateContext failed for hidden OpenGL window.";
+		return false;
+	}
+	if (sharedContext != nullptr && wglShareLists(sharedContext, mGlrc) != TRUE)
+	{
+		error = "wglShareLists failed for hidden OpenGL shared context.";
+		return false;
+	}
+
+	return true;
+}
+
+bool HiddenGlWindow::MakeCurrent() const
+{
+	return mDc != nullptr && mGlrc != nullptr && wglMakeCurrent(mDc, mGlrc) == TRUE;
+}
+
+void HiddenGlWindow::ClearCurrent() const
+{
+	wglMakeCurrent(nullptr, nullptr);
+}
+
+void HiddenGlWindow::Destroy()
+{
+	ClearCurrent();
+
+	if (mGlrc)
+	{
+		wglDeleteContext(mGlrc);
+		mGlrc = nullptr;
+	}
+	if (mWindow && mDc)
+	{
+		ReleaseDC(mWindow, mDc);
+		mDc = nullptr;
+	}
+	if (mWindow)
+	{
+		DestroyWindow(mWindow);
+		mWindow = nullptr;
+	}
+
+	mInstance = nullptr;
+	mClassAtom = 0;
+}
+
+LRESULT CALLBACK HiddenGlWindow::WindowProc(HWND hwnd, UINT message, WPARAM wParam, LPARAM lParam)
+{
+	return DefWindowProc(hwnd, message, wParam, lParam);
+}

apps/RenderCadenceCompositor/platform/HiddenGlWindow.h

@@ -0,0 +1,32 @@
+#pragma once
+
+#include <windows.h>
+
+#include <string>
+
+class HiddenGlWindow
+{
+public:
+	HiddenGlWindow() = default;
+	HiddenGlWindow(const HiddenGlWindow&) = delete;
+	HiddenGlWindow& operator=(const HiddenGlWindow&) = delete;
+	~HiddenGlWindow();
+
+	bool Create(unsigned width, unsigned height, std::string& error);
+	bool CreateShared(unsigned width, unsigned height, HDC sharedDeviceContext, HGLRC sharedContext, std::string& error);
+	bool MakeCurrent() const;
+	void ClearCurrent() const;
+	void Destroy();
+
+	HDC DeviceContext() const { return mDc; }
+	HGLRC Context() const { return mGlrc; }
+
+private:
+	static LRESULT CALLBACK WindowProc(HWND hwnd, UINT message, WPARAM wParam, LPARAM lParam);
+
+	HINSTANCE mInstance = nullptr;
+	HWND mWindow = nullptr;
+	HDC mDc = nullptr;
+	HGLRC mGlrc = nullptr;
+	ATOM mClassAtom = 0;
+};

apps/RenderCadenceCompositor/render/Bgra8ReadbackPipeline.cpp

@@ -0,0 +1,142 @@
+#include "Bgra8ReadbackPipeline.h"
+
+#include "../frames/SystemFrameTypes.h"
+
+#include <cstring>
+
+Bgra8ReadbackPipeline::~Bgra8ReadbackPipeline()
+{
+	Shutdown();
+}
+
+bool Bgra8ReadbackPipeline::Initialize(unsigned width, unsigned height, std::size_t pboDepth)
+{
+	Shutdown();
+
+	mWidth = width;
+	mHeight = height;
+	mRowBytes = VideoIORowBytes(VideoIOPixelFormat::Bgra8, width);
+	if (mWidth == 0 || mHeight == 0 || mRowBytes == 0)
+		return false;
+
+	if (!CreateRenderTarget())
+	{
+		Shutdown();
+		return false;
+	}
+
+	const std::size_t byteCount = static_cast<std::size_t>(mRowBytes) * static_cast<std::size_t>(mHeight);
+	if (!mPboRing.Initialize(pboDepth, byteCount))
+	{
+		Shutdown();
+		return false;
+	}
+
+	return true;
+}
+
+void Bgra8ReadbackPipeline::Shutdown()
+{
+	mPboRing.Shutdown();
+	DestroyRenderTarget();
+	mWidth = 0;
+	mHeight = 0;
+	mRowBytes = 0;
+}
+
+bool Bgra8ReadbackPipeline::RenderAndQueue(uint64_t frameIndex, const RenderCallback& renderFrame)
+{
+	if (mFramebuffer == 0 || !renderFrame)
+		return false;
+
+	glBindFramebuffer(GL_FRAMEBUFFER, mFramebuffer);
+	renderFrame(frameIndex);
+	glBindFramebuffer(GL_FRAMEBUFFER, 0);
+
+	return mPboRing.QueueReadback(mFramebuffer, mWidth, mHeight, frameIndex);
+}
+
+void Bgra8ReadbackPipeline::ConsumeCompleted(
+	const AcquireFrameCallback& acquireFrame,
+	const PublishFrameCallback& publishFrame,
+	const CounterCallback& onAcquireMiss,
+	const CounterCallback& onCompleted)
+{
+	if (!acquireFrame || !publishFrame)
+		return;
+
+	PboReadbackRing::CompletedReadback readback;
+	while (mPboRing.TryAcquireCompleted(readback))
+	{
+		glBindBuffer(GL_PIXEL_PACK_BUFFER, readback.pbo);
+		void* mapped = glMapBuffer(GL_PIXEL_PACK_BUFFER, GL_READ_ONLY);
+		if (!mapped)
+		{
+			glBindBuffer(GL_PIXEL_PACK_BUFFER, 0);
+			mPboRing.ReleaseCompleted(readback);
+			continue;
+		}
+
+		SystemFrame frame;
+		if (acquireFrame(frame))
+		{
+			const std::size_t byteCount = static_cast<std::size_t>(frame.rowBytes) * static_cast<std::size_t>(frame.height);
+			if (frame.bytes != nullptr && byteCount <= readback.byteCount)
+			{
+				std::memcpy(frame.bytes, mapped, byteCount);
+				frame.frameIndex = readback.frameIndex;
+				frame.pixelFormat = VideoIOPixelFormat::Bgra8;
+				publishFrame(frame);
+				if (onCompleted)
+					onCompleted();
+			}
+		}
+		else if (onAcquireMiss)
+		{
+			onAcquireMiss();
+		}
+
+		glUnmapBuffer(GL_PIXEL_PACK_BUFFER);
+		glBindBuffer(GL_PIXEL_PACK_BUFFER, 0);
+		mPboRing.ReleaseCompleted(readback);
+	}
+}
+
+bool Bgra8ReadbackPipeline::CreateRenderTarget()
+{
+	glGenFramebuffers(1, &mFramebuffer);
+	glBindFramebuffer(GL_FRAMEBUFFER, mFramebuffer);
+
+	glGenTextures(1, &mTexture);
+	glBindTexture(GL_TEXTURE_2D, mTexture);
+	glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_NEAREST);
+	glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MAG_FILTER, GL_NEAREST);
+	glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_S, GL_CLAMP_TO_EDGE);
+	glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_T, GL_CLAMP_TO_EDGE);
+	glTexImage2D(
+		GL_TEXTURE_2D,
+		0,
+		GL_RGBA8,
+		static_cast<GLsizei>(mWidth),
+		static_cast<GLsizei>(mHeight),
+		0,
+		GL_BGRA,
+		GL_UNSIGNED_INT_8_8_8_8_REV,
+		nullptr);
+	glFramebufferTexture2D(GL_FRAMEBUFFER, GL_COLOR_ATTACHMENT0, GL_TEXTURE_2D, mTexture, 0);
+
+	const bool complete = glCheckFramebufferStatus(GL_FRAMEBUFFER) == GL_FRAMEBUFFER_COMPLETE;
+	glBindTexture(GL_TEXTURE_2D, 0);
+	glBindFramebuffer(GL_FRAMEBUFFER, 0);
+	return complete;
+}
+
+void Bgra8ReadbackPipeline::DestroyRenderTarget()
+{
+	if (mFramebuffer != 0)
+		glDeleteFramebuffers(1, &mFramebuffer);
+	if (mTexture != 0)
+		glDeleteTextures(1, &mTexture);
+	mFramebuffer = 0;
+	mTexture = 0;
+}

apps/RenderCadenceCompositor/render/Bgra8ReadbackPipeline.h

@@ -0,0 +1,52 @@
+#pragma once
+
+#include "PboReadbackRing.h"
+#include "VideoIOFormat.h"
+
+#include <cstddef>
+#include <cstdint>
+#include <functional>
+
+struct SystemFrame;
+
+class Bgra8ReadbackPipeline
+{
+public:
+	using RenderCallback = std::function<void(uint64_t frameIndex)>;
+	using AcquireFrameCallback = std::function<bool(SystemFrame& frame)>;
+	using PublishFrameCallback = std::function<bool(const SystemFrame& frame)>;
+	using CounterCallback = std::function<void()>;
+
+	Bgra8ReadbackPipeline() = default;
+	Bgra8ReadbackPipeline(const Bgra8ReadbackPipeline&) = delete;
+	Bgra8ReadbackPipeline& operator=(const Bgra8ReadbackPipeline&) = delete;
+	~Bgra8ReadbackPipeline();
+
+	bool Initialize(unsigned width, unsigned height, std::size_t pboDepth);
+	void Shutdown();
+
+	bool RenderAndQueue(uint64_t frameIndex, const RenderCallback& renderFrame);
+	void ConsumeCompleted(
+		const AcquireFrameCallback& acquireFrame,
+		const PublishFrameCallback& publishFrame,
+		const CounterCallback& onAcquireMiss = {},
+		const CounterCallback& onCompleted = {});
+
+	GLuint Framebuffer() const { return mFramebuffer; }
+	unsigned Width() const { return mWidth; }
+	unsigned Height() const { return mHeight; }
+	unsigned RowBytes() const { return mRowBytes; }
+	VideoIOPixelFormat PixelFormat() const { return VideoIOPixelFormat::Bgra8; }
+	uint64_t PboQueueMisses() const { return mPboRing.QueueMisses(); }
+
+private:
+	bool CreateRenderTarget();
+	void DestroyRenderTarget();
+
+	unsigned mWidth = 0;
+	unsigned mHeight = 0;
+	unsigned mRowBytes = 0;
+	GLuint mFramebuffer = 0;
+	GLuint mTexture = 0;
+	PboReadbackRing mPboRing;
+};

apps/RenderCadenceCompositor/render/PboReadbackRing.cpp

@@ -0,0 +1,138 @@
+#include "PboReadbackRing.h"
+
+#include <algorithm>
+
+PboReadbackRing::~PboReadbackRing()
+{
+	Shutdown();
+}
+
+bool PboReadbackRing::Initialize(std::size_t depth, std::size_t byteCount)
+{
+	Shutdown();
+	if (depth == 0 || byteCount == 0)
+		return false;
+
+	mSlots.resize(depth);
+	mByteCount = byteCount;
+	for (Slot& slot : mSlots)
+	{
+		glGenBuffers(1, &slot.pbo);
+		if (slot.pbo == 0)
+		{
+			Shutdown();
+			return false;
+		}
+		glBindBuffer(GL_PIXEL_PACK_BUFFER, slot.pbo);
+		glBufferData(GL_PIXEL_PACK_BUFFER, static_cast<GLsizeiptr>(mByteCount), nullptr, GL_STREAM_READ);
+	}
+	glBindBuffer(GL_PIXEL_PACK_BUFFER, 0);
+	return true;
+}
+
+void PboReadbackRing::Shutdown()
+{
+	for (Slot& slot : mSlots)
+	{
+		if (slot.fence)
+			glDeleteSync(slot.fence);
+		if (slot.pbo != 0)
+			glDeleteBuffers(1, &slot.pbo);
+		slot = {};
+	}
+	mSlots.clear();
+	mWriteIndex = 0;
+	mReadIndex = 0;
+	mByteCount = 0;
+}
+
+bool PboReadbackRing::QueueReadback(GLuint framebuffer, unsigned width, unsigned height, uint64_t frameIndex)
+{
+	if (mSlots.empty())
+		return false;
+
+	Slot& slot = mSlots[mWriteIndex];
+	if (slot.inFlight || slot.acquired)
+	{
+		++mQueueMisses;
+		return false;
+	}
+
+	glBindFramebuffer(GL_READ_FRAMEBUFFER, framebuffer);
+	glPixelStorei(GL_PACK_ALIGNMENT, 4);
+	glPixelStorei(GL_PACK_ROW_LENGTH, 0);
+	glBindBuffer(GL_PIXEL_PACK_BUFFER, slot.pbo);
+	glBufferData(GL_PIXEL_PACK_BUFFER, static_cast<GLsizeiptr>(mByteCount), nullptr, GL_STREAM_READ);
+	glReadPixels(0, 0, static_cast<GLsizei>(width), static_cast<GLsizei>(height), GL_BGRA, GL_UNSIGNED_INT_8_8_8_8_REV, nullptr);
+	slot.fence = glFenceSync(GL_SYNC_GPU_COMMANDS_COMPLETE, 0);
+	slot.inFlight = slot.fence != nullptr;
+	slot.frameIndex = frameIndex;
+	glBindBuffer(GL_PIXEL_PACK_BUFFER, 0);
+
+	if (!slot.inFlight)
+		return false;
+
+	mWriteIndex = (mWriteIndex + 1) % mSlots.size();
+	return true;
+}
+
+bool PboReadbackRing::TryAcquireCompleted(CompletedReadback& readback)
+{
+	if (mSlots.empty())
+		return false;
+
+	for (std::size_t checked = 0; checked < mSlots.size(); ++checked)
+	{
+		Slot& slot = mSlots[mReadIndex];
+		if (!slot.inFlight || slot.acquired || slot.fence == nullptr)
+		{
+			mReadIndex = (mReadIndex + 1) % mSlots.size();
+			continue;
+		}
+
+		const GLenum waitResult = glClientWaitSync(slot.fence, 0, 0);
+		if (waitResult != GL_ALREADY_SIGNALED && waitResult != GL_CONDITION_SATISFIED)
+			return false;
+
+		slot.acquired = true;
+		readback.pbo = slot.pbo;
+		readback.frameIndex = slot.frameIndex;
+		readback.byteCount = mByteCount;
+		return true;
+	}
+	return false;
+}
+
+void PboReadbackRing::ReleaseCompleted(const CompletedReadback& readback)
+{
+	for (std::size_t index = 0; index < mSlots.size(); ++index)
+	{
+		Slot& slot = mSlots[index];
+		if (!slot.acquired || slot.pbo != readback.pbo)
+			continue;
+		ResetSlot(slot);
+		mReadIndex = (index + 1) % mSlots.size();
+		return;
+	}
+}
+
+void PboReadbackRing::DrainCompleted()
+{
+	for (std::size_t pass = 0; pass < mSlots.size() * 2; ++pass)
+	{
+		CompletedReadback readback;
+		if (!TryAcquireCompleted(readback))
+			break;
+		ReleaseCompleted(readback);
+	}
+}
+
+void PboReadbackRing::ResetSlot(Slot& slot)
+{
+	if (slot.fence)
+		glDeleteSync(slot.fence);
+	slot.fence = nullptr;
+	slot.inFlight = false;
+	slot.acquired = false;
+	slot.frameIndex = 0;
+}

apps/RenderCadenceCompositor/render/PboReadbackRing.h

@@ -0,0 +1,52 @@
+#pragma once
+
+#include "GLExtensions.h"
+
+#include <cstddef>
+#include <cstdint>
+#include <vector>
+
+class PboReadbackRing
+{
+public:
+	struct CompletedReadback
+	{
+		GLuint pbo = 0;
+		uint64_t frameIndex = 0;
+		std::size_t byteCount = 0;
+	};
+
+	PboReadbackRing() = default;
+	PboReadbackRing(const PboReadbackRing&) = delete;
+	PboReadbackRing& operator=(const PboReadbackRing&) = delete;
+	~PboReadbackRing();
+
+	bool Initialize(std::size_t depth, std::size_t byteCount);
+	void Shutdown();
+
+	bool QueueReadback(GLuint framebuffer, unsigned width, unsigned height, uint64_t frameIndex);
+	bool TryAcquireCompleted(CompletedReadback& readback);
+	void ReleaseCompleted(const CompletedReadback& readback);
+	void DrainCompleted();
+
+	std::size_t Depth() const { return mSlots.size(); }
+	uint64_t QueueMisses() const { return mQueueMisses; }
+
+private:
+	struct Slot
+	{
+		GLuint pbo = 0;
+		GLsync fence = nullptr;
+		bool inFlight = false;
+		bool acquired = false;
+		uint64_t frameIndex = 0;
+	};
+
+	void ResetSlot(Slot& slot);
+
+	std::vector<Slot> mSlots;
+	std::size_t mWriteIndex = 0;
+	std::size_t mReadIndex = 0;
+	std::size_t mByteCount = 0;
+	uint64_t mQueueMisses = 0;
+};

apps/RenderCadenceCompositor/render/RenderCadenceClock.cpp

@@ -0,0 +1,45 @@
+#include "RenderCadenceClock.h"
+
+#include <algorithm>
+
+RenderCadenceClock::RenderCadenceClock(double frameDurationMilliseconds)
+{
+	mFrameDuration = std::chrono::duration_cast<Duration>(std::chrono::duration<double, std::milli>(frameDurationMilliseconds));
+	if (mFrameDuration <= Duration::zero())
+		mFrameDuration = std::chrono::milliseconds(16);
+	Reset();
+}
+
+void RenderCadenceClock::Reset(TimePoint now)
+{
+	mNextRenderTime = now;
+	mOverrunCount = 0;
+	mSkippedFrameCount = 0;
+}
+
+RenderCadenceClock::Tick RenderCadenceClock::Poll(TimePoint now)
+{
+	Tick tick;
+	if (now < mNextRenderTime)
+	{
+		tick.sleepFor = std::min(Duration(std::chrono::milliseconds(1)), mNextRenderTime - now);
+		return tick;
+	}
+
+	tick.due = true;
+	const Duration lateBy = now - mNextRenderTime;
+	if (lateBy > mFrameDuration)
+	{
+		tick.skippedFrames = static_cast<uint64_t>(lateBy / mFrameDuration);
+		++mOverrunCount;
+		mSkippedFrameCount += tick.skippedFrames;
+	}
+	return tick;
+}
+
+void RenderCadenceClock::MarkRendered(TimePoint now)
+{
+	mNextRenderTime += mFrameDuration;
+	if (now - mNextRenderTime > mFrameDuration * 4)
+		mNextRenderTime = now + mFrameDuration;
+}

apps/RenderCadenceCompositor/render/RenderCadenceClock.h

@@ -0,0 +1,36 @@
+#pragma once
+
+#include <chrono>
+#include <cstdint>
+
+class RenderCadenceClock
+{
+public:
+	using Clock = std::chrono::steady_clock;
+	using Duration = Clock::duration;
+	using TimePoint = Clock::time_point;
+
+	struct Tick
+	{
+		bool due = false;
+		uint64_t skippedFrames = 0;
+		Duration sleepFor = Duration::zero();
+	};
+
+	explicit RenderCadenceClock(double frameDurationMilliseconds = 1000.0 / 60.0);
+
+	void Reset(TimePoint now = Clock::now());
+	Tick Poll(TimePoint now = Clock::now());
+	void MarkRendered(TimePoint now = Clock::now());
+
+	Duration FrameDuration() const { return mFrameDuration; }
+	TimePoint NextRenderTime() const { return mNextRenderTime; }
+	uint64_t OverrunCount() const { return mOverrunCount; }
+	uint64_t SkippedFrameCount() const { return mSkippedFrameCount; }
+
+private:
+	Duration mFrameDuration;
+	TimePoint mNextRenderTime = Clock::now();
+	uint64_t mOverrunCount = 0;
+	uint64_t mSkippedFrameCount = 0;
+};

apps/RenderCadenceCompositor/render/RenderThread.cpp

@@ -0,0 +1,304 @@
+#include "RenderThread.h"
+
+#include "../frames/SystemFrameExchange.h"
+#include "../frames/SystemFrameTypes.h"
+#include "../logging/Logger.h"
+#include "../platform/HiddenGlWindow.h"
+#include "Bgra8ReadbackPipeline.h"
+#include "GLExtensions.h"
+#include "RuntimeRenderScene.h"
+#include "RuntimeShaderRenderer.h"
+#include "SimpleMotionRenderer.h"
+
+#include <algorithm>
+#include <memory>
+#include <thread>
+
+RenderThread::RenderThread(SystemFrameExchange& frameExchange, Config config) :
+	mFrameExchange(frameExchange),
+	mConfig(config)
+{
+}
+
+RenderThread::~RenderThread()
+{
+	Stop();
+}
+
+bool RenderThread::Start(std::string& error)
+{
+	if (mThread.joinable())
+		return true;
+
+	{
+		std::lock_guard<std::mutex> lock(mStartupMutex);
+		mStarted = false;
+		mStartupError.clear();
+	}
+
+	mStopping.store(false, std::memory_order_release);
+	mThread = std::thread([this]() { ThreadMain(); });
+
+	std::unique_lock<std::mutex> lock(mStartupMutex);
+	if (!mStartupCondition.wait_for(lock, std::chrono::seconds(3), [this]() {
+		return mStarted || !mStartupError.empty();
+	}))
+	{
+		error = "Timed out starting render thread.";
+		return false;
+	}
+	if (!mStartupError.empty())
+	{
+		error = mStartupError;
+		lock.unlock();
+		if (mThread.joinable())
+			mThread.join();
+		return false;
+	}
+	return true;
+}
+
+void RenderThread::Stop()
+{
+	mStopping.store(true, std::memory_order_release);
+	if (mThread.joinable())
+		mThread.join();
+}
+
+RenderThread::Metrics RenderThread::GetMetrics() const
+{
+	Metrics metrics;
+	metrics.renderedFrames = mRenderedFrames.load(std::memory_order_relaxed);
+	metrics.completedReadbacks = mCompletedReadbacks.load(std::memory_order_relaxed);
+	metrics.acquireMisses = mAcquireMisses.load(std::memory_order_relaxed);
+	metrics.pboQueueMisses = mPboQueueMisses.load(std::memory_order_relaxed);
+	metrics.clockOverruns = mClockOverruns.load(std::memory_order_relaxed);
+	metrics.skippedFrames = mSkippedFrames.load(std::memory_order_relaxed);
+	metrics.shaderBuildsCommitted = mShaderBuildsCommitted.load(std::memory_order_relaxed);
+	metrics.shaderBuildFailures = mShaderBuildFailures.load(std::memory_order_relaxed);
+	return metrics;
+}
+
+void RenderThread::ThreadMain()
+{
+	RenderCadenceCompositor::TryLog(RenderCadenceCompositor::LogLevel::Log, "render-thread", "Render thread starting.");
+	HiddenGlWindow window;
+	std::string error;
+	if (!window.Create(mConfig.width, mConfig.height, error))
+	{
+		SignalStartupFailure(error.empty() ? "OpenGL context creation failed." : error);
+		return;
+	}
+	std::unique_ptr<HiddenGlWindow> prepareWindow = std::make_unique<HiddenGlWindow>();
+	if (!prepareWindow->CreateShared(mConfig.width, mConfig.height, window.DeviceContext(), window.Context(), error))
+	{
+		SignalStartupFailure(error.empty() ? "Runtime shader prepare shared context creation failed." : error);
+		return;
+	}
+	if (!window.MakeCurrent())
+	{
+		SignalStartupFailure("OpenGL context creation failed.");
+		return;
+	}
+	if (!ResolveGLExtensions())
+	{
+		SignalStartupFailure("OpenGL extension resolution failed.");
+		return;
+	}
+
+	SimpleMotionRenderer renderer;
+	RuntimeRenderScene runtimeRenderScene;
+	Bgra8ReadbackPipeline readback;
+	if (!runtimeRenderScene.StartPrepareWorker(std::move(prepareWindow), error))
+	{
+		SignalStartupFailure(error.empty() ? "Runtime shader prepare worker initialization failed." : error);
+		return;
+	}
+	if (!renderer.InitializeGl(mConfig.width, mConfig.height) || !readback.Initialize(mConfig.width, mConfig.height, mConfig.pboDepth))
+	{
+		SignalStartupFailure("Render pipeline initialization failed.");
+		return;
+	}
+
+	RenderCadenceClock clock(mConfig.frameDurationMilliseconds);
+	uint64_t frameIndex = 0;
+	mRunning.store(true, std::memory_order_release);
+	SignalStarted();
+
+	while (!mStopping.load(std::memory_order_acquire))
+	{
+		readback.ConsumeCompleted(
+			[this](SystemFrame& frame) { return mFrameExchange.AcquireForRender(frame); },
+			[this](const SystemFrame& frame) { return mFrameExchange.PublishCompleted(frame); },
+			[this]() {
+				CountAcquireMiss();
+			},
+			[this]() { CountCompleted(); });
+
+		const auto now = RenderCadenceClock::Clock::now();
+		const RenderCadenceClock::Tick tick = clock.Poll(now);
+		if (!tick.due)
+		{
+			if (tick.sleepFor > RenderCadenceClock::Duration::zero())
+				std::this_thread::sleep_for(tick.sleepFor);
+			continue;
+		}
+
+		TryCommitReadyRuntimeShader(runtimeRenderScene);
+		if (!readback.RenderAndQueue(frameIndex, [this, &renderer, &runtimeRenderScene](uint64_t index) {
+			if (runtimeRenderScene.HasLayers())
+				runtimeRenderScene.RenderFrame(index, mConfig.width, mConfig.height);
+			else
+				renderer.RenderFrame(index);
+		}))
+		{
+			mPboQueueMisses.fetch_add(1, std::memory_order_relaxed);
+		}
+
+		CountRendered();
+		++frameIndex;
+		clock.MarkRendered(RenderCadenceClock::Clock::now());
+
+		mClockOverruns.store(clock.OverrunCount(), std::memory_order_relaxed);
+		mSkippedFrames.store(clock.SkippedFrameCount(), std::memory_order_relaxed);
+	}
+
+	for (std::size_t i = 0; i < mConfig.pboDepth * 2; ++i)
+	{
+		readback.ConsumeCompleted(
+			[this](SystemFrame& frame) { return mFrameExchange.AcquireForRender(frame); },
+			[this](const SystemFrame& frame) { return mFrameExchange.PublishCompleted(frame); },
+			[this]() {
+				CountAcquireMiss();
+			},
+			[this]() { CountCompleted(); });
+	}
+
+	readback.Shutdown();
+	runtimeRenderScene.ShutdownGl();
+	renderer.ShutdownGl();
+	window.ClearCurrent();
+	mRunning.store(false, std::memory_order_release);
+	RenderCadenceCompositor::TryLog(RenderCadenceCompositor::LogLevel::Log, "render-thread", "Render thread stopped.");
+}
+
+void RenderThread::SignalStarted()
+{
+	std::lock_guard<std::mutex> lock(mStartupMutex);
+	mStarted = true;
+	mStartupCondition.notify_all();
+}
+
+void RenderThread::SignalStartupFailure(const std::string& error)
+{
+	RenderCadenceCompositor::TryLog(RenderCadenceCompositor::LogLevel::Error, "render-thread", error);
+	std::lock_guard<std::mutex> lock(mStartupMutex);
+	mStartupError = error;
+	mStartupCondition.notify_all();
+}
+
+void RenderThread::CountRendered()
+{
+	mRenderedFrames.fetch_add(1, std::memory_order_relaxed);
+}
+
+void RenderThread::CountCompleted()
+{
+	mCompletedReadbacks.fetch_add(1, std::memory_order_relaxed);
+}
+
+void RenderThread::CountAcquireMiss()
+{
+	mAcquireMisses.fetch_add(1, std::memory_order_relaxed);
+}
+
+void RenderThread::SubmitRuntimeShaderArtifact(const RuntimeShaderArtifact& artifact)
+{
+	if (artifact.fragmentShaderSource.empty())
+		return;
+
+	std::lock_guard<std::mutex> lock(mShaderArtifactMutex);
+	mPendingShaderArtifact = artifact;
+	mHasPendingShaderArtifact = true;
+}
+
+void RenderThread::SubmitRuntimeRenderLayers(const std::vector<RenderCadenceCompositor::RuntimeRenderLayerModel>& layers)
+{
+	std::lock_guard<std::mutex> lock(mRenderLayersMutex);
+	mPendingRenderLayers = layers;
+	mHasPendingRenderLayers = true;
+}
+
+bool RenderThread::TryTakePendingRuntimeShaderArtifact(RuntimeShaderArtifact& artifact)
+{
+	std::lock_guard<std::mutex> lock(mShaderArtifactMutex);
+	if (!mHasPendingShaderArtifact)
+		return false;
+
+	artifact = std::move(mPendingShaderArtifact);
+	mPendingShaderArtifact = RuntimeShaderArtifact();
+	mHasPendingShaderArtifact = false;
+	return true;
+}
+
+bool RenderThread::TryTakePendingRenderLayers(std::vector<RenderCadenceCompositor::RuntimeRenderLayerModel>& layers)
+{
+	std::lock_guard<std::mutex> lock(mRenderLayersMutex);
+	if (!mHasPendingRenderLayers)
+		return false;
+
+	layers = std::move(mPendingRenderLayers);
+	mPendingRenderLayers.clear();
+	mHasPendingRenderLayers = false;
+	return true;
+}
+
+void RenderThread::TryCommitReadyRuntimeShader(RuntimeRenderScene& runtimeRenderScene)
+{
+	std::vector<RenderCadenceCompositor::RuntimeRenderLayerModel> layers;
+	std::string commitError;
+	if (TryTakePendingRenderLayers(layers))
+	{
+		if (!runtimeRenderScene.CommitRenderLayers(layers, commitError))
+		{
+			RenderCadenceCompositor::TryLog(
+				RenderCadenceCompositor::LogLevel::Error,
+				"render-thread",
+				"Runtime render-layer commit failed: " + commitError);
+			mShaderBuildFailures.fetch_add(1, std::memory_order_relaxed);
+			return;
+		}
+
+		RenderCadenceCompositor::TryLog(
+			RenderCadenceCompositor::LogLevel::Log,
+			"render-thread",
+			"Runtime render layer snapshot committed.");
+		mShaderBuildsCommitted.fetch_add(1, std::memory_order_relaxed);
+		return;
+	}
+
+	RuntimeShaderArtifact artifact;
+	if (!TryTakePendingRuntimeShaderArtifact(artifact))
+		return;
+
+	RenderCadenceCompositor::RuntimeRenderLayerModel layer;
+	layer.id = artifact.layerId.empty() ? "runtime-layer-1" : artifact.layerId;
+	layer.shaderId = artifact.shaderId;
+	layer.artifact = artifact;
+	layers.push_back(std::move(layer));
+	if (!runtimeRenderScene.CommitRenderLayers(layers, commitError))
+	{
+		RenderCadenceCompositor::TryLog(
+			RenderCadenceCompositor::LogLevel::Error,
+			"render-thread",
+			"Runtime shader GL commit failed: " + commitError);
+		mShaderBuildFailures.fetch_add(1, std::memory_order_relaxed);
+		return;
+	}
+
+	RenderCadenceCompositor::TryLog(
+		RenderCadenceCompositor::LogLevel::Log,
+		"render-thread",
+		"Runtime shader committed: " + artifact.shaderId + ". " + artifact.message);
+	mShaderBuildsCommitted.fetch_add(1, std::memory_order_relaxed);
+}

apps/RenderCadenceCompositor/render/RenderThread.h

@@ -0,0 +1,92 @@
+#pragma once
+
+#include "RenderCadenceClock.h"
+#include "../runtime/RuntimeLayerModel.h"
+#include "../runtime/RuntimeShaderArtifact.h"
+#include "RuntimeRenderScene.h"
+
+#include <atomic>
+#include <condition_variable>
+#include <cstddef>
+#include <cstdint>
+#include <mutex>
+#include <string>
+#include <thread>
+
+class SystemFrameExchange;
+
+class RenderThread
+{
+public:
+	struct Config
+	{
+		unsigned width = 1920;
+		unsigned height = 1080;
+		double frameDurationMilliseconds = 1000.0 / 59.94;
+		std::size_t pboDepth = 6;
+	};
+
+	struct Metrics
+	{
+		uint64_t renderedFrames = 0;
+		uint64_t completedReadbacks = 0;
+		uint64_t acquireMisses = 0;
+		uint64_t pboQueueMisses = 0;
+		uint64_t clockOverruns = 0;
+		uint64_t skippedFrames = 0;
+		uint64_t shaderBuildsCommitted = 0;
+		uint64_t shaderBuildFailures = 0;
+	};
+
+	RenderThread(SystemFrameExchange& frameExchange, Config config);
+	RenderThread(const RenderThread&) = delete;
+	RenderThread& operator=(const RenderThread&) = delete;
+	~RenderThread();
+
+	bool Start(std::string& error);
+	void Stop();
+	void SubmitRuntimeShaderArtifact(const RuntimeShaderArtifact& artifact);
+	void SubmitRuntimeRenderLayers(const std::vector<RenderCadenceCompositor::RuntimeRenderLayerModel>& layers);
+
+	Metrics GetMetrics() const;
+	bool IsRunning() const { return mRunning.load(std::memory_order_acquire); }
+
+private:
+	void ThreadMain();
+	void SignalStarted();
+	void SignalStartupFailure(const std::string& error);
+	void CountRendered();
+	void CountCompleted();
+	void CountAcquireMiss();
+	void TryCommitReadyRuntimeShader(RuntimeRenderScene& runtimeRenderScene);
+	bool TryTakePendingRuntimeShaderArtifact(RuntimeShaderArtifact& artifact);
+	bool TryTakePendingRenderLayers(std::vector<RenderCadenceCompositor::RuntimeRenderLayerModel>& layers);
+
+	SystemFrameExchange& mFrameExchange;
+	Config mConfig;
+	std::thread mThread;
+	std::atomic<bool> mStopping{ false };
+	std::atomic<bool> mRunning{ false };
+
+	mutable std::mutex mStartupMutex;
+	std::condition_variable mStartupCondition;
+	bool mStarted = false;
+	std::string mStartupError;
+
+	std::atomic<uint64_t> mRenderedFrames{ 0 };
+	std::atomic<uint64_t> mCompletedReadbacks{ 0 };
+	std::atomic<uint64_t> mAcquireMisses{ 0 };
+	std::atomic<uint64_t> mPboQueueMisses{ 0 };
+	std::atomic<uint64_t> mClockOverruns{ 0 };
+	std::atomic<uint64_t> mSkippedFrames{ 0 };
+	std::atomic<uint64_t> mShaderBuildsCommitted{ 0 };
+	std::atomic<uint64_t> mShaderBuildFailures{ 0 };
+
+	std::mutex mShaderArtifactMutex;
+	bool mHasPendingShaderArtifact = false;
+	RuntimeShaderArtifact mPendingShaderArtifact;
+
+	std::mutex mRenderLayersMutex;
+	bool mHasPendingRenderLayers = false;
+	std::vector<RenderCadenceCompositor::RuntimeRenderLayerModel> mPendingRenderLayers;
+};

apps/RenderCadenceCompositor/render/RuntimeRenderScene.cpp

@@ -0,0 +1,173 @@
+#include "RuntimeRenderScene.h"
+
+#include "../platform/HiddenGlWindow.h"
+
+#include <algorithm>
+#include <functional>
+#include <utility>
+
+RuntimeRenderScene::~RuntimeRenderScene()
+{
+	ShutdownGl();
+}
+
+bool RuntimeRenderScene::StartPrepareWorker(std::unique_ptr<HiddenGlWindow> sharedWindow, std::string& error)
+{
+	return mPrepareWorker.Start(std::move(sharedWindow), error);
+}
+
+bool RuntimeRenderScene::CommitRenderLayers(const std::vector<RenderCadenceCompositor::RuntimeRenderLayerModel>& layers, std::string& error)
+{
+	ConsumePreparedPrograms();
+
+	std::vector<std::string> nextOrder;
+	std::vector<RenderCadenceCompositor::RuntimeRenderLayerModel> layersToPrepare;
+	nextOrder.reserve(layers.size());
+	for (const RenderCadenceCompositor::RuntimeRenderLayerModel& layer : layers)
+		nextOrder.push_back(layer.id);
+
+	for (auto layerIt = mLayers.begin(); layerIt != mLayers.end();)
+	{
+		const bool stillPresent = std::find(nextOrder.begin(), nextOrder.end(), layerIt->layerId) != nextOrder.end();
+		if (stillPresent)
+		{
+			++layerIt;
+			continue;
+		}
+
+		if (layerIt->renderer)
+			layerIt->renderer->ShutdownGl();
+		layerIt = mLayers.erase(layerIt);
+	}
+
+	for (const RenderCadenceCompositor::RuntimeRenderLayerModel& layer : layers)
+	{
+		if (layer.artifact.fragmentShaderSource.empty())
+			continue;
+
+		const std::string fingerprint = Fingerprint(layer.artifact);
+		LayerProgram* program = FindLayer(layer.id);
+		if (!program)
+		{
+			LayerProgram next;
+			next.layerId = layer.id;
+			next.renderer = std::make_unique<RuntimeShaderRenderer>();
+			mLayers.push_back(std::move(next));
+			program = &mLayers.back();
+		}
+
+		if (program->shaderId == layer.shaderId && program->sourceFingerprint == fingerprint && program->renderer && program->renderer->HasProgram())
+			continue;
+		if (program->pendingFingerprint == fingerprint)
+			continue;
+
+		program->shaderId = layer.shaderId;
+		program->pendingFingerprint = fingerprint;
+		layersToPrepare.push_back(layer);
+	}
+
+	mLayerOrder = std::move(nextOrder);
+	if (!layersToPrepare.empty())
+		mPrepareWorker.Submit(layersToPrepare);
+	error.clear();
+	return true;
+}
+
+bool RuntimeRenderScene::HasLayers()
+{
+	ConsumePreparedPrograms();
+
+	for (const std::string& layerId : mLayerOrder)
+	{
+		const LayerProgram* layer = FindLayer(layerId);
+		if (layer && layer->renderer && layer->renderer->HasProgram())
+			return true;
+	}
+	return false;
+}
+
+void RuntimeRenderScene::RenderFrame(uint64_t frameIndex, unsigned width, unsigned height)
+{
+	ConsumePreparedPrograms();
+
+	for (const std::string& layerId : mLayerOrder)
+	{
+		LayerProgram* layer = FindLayer(layerId);
+		if (!layer || !layer->renderer || !layer->renderer->HasProgram())
+			continue;
+		layer->renderer->RenderFrame(frameIndex, width, height);
+	}
+}
+
+void RuntimeRenderScene::ShutdownGl()
+{
+	mPrepareWorker.Stop();
+	for (LayerProgram& layer : mLayers)
+	{
+		if (layer.renderer)
+			layer.renderer->ShutdownGl();
+	}
+	mLayers.clear();
+	mLayerOrder.clear();
+}
+
+void RuntimeRenderScene::ConsumePreparedPrograms()
+{
+	RuntimePreparedShaderProgram preparedProgram;
+	while (mPrepareWorker.TryConsume(preparedProgram))
+	{
+		if (!preparedProgram.succeeded)
+		{
+			preparedProgram.ReleaseGl();
+			continue;
+		}
+
+		LayerProgram* layer = FindLayer(preparedProgram.layerId);
+		if (!layer || layer->pendingFingerprint != preparedProgram.sourceFingerprint)
+		{
+			preparedProgram.ReleaseGl();
+			continue;
+		}
+
+		std::unique_ptr<RuntimeShaderRenderer> nextRenderer = std::make_unique<RuntimeShaderRenderer>();
+		std::string error;
+		if (!nextRenderer->CommitPreparedProgram(preparedProgram, error))
+		{
+			preparedProgram.ReleaseGl();
+			continue;
+		}
+
+		if (layer->renderer)
+			layer->renderer->ShutdownGl();
+		layer->renderer = std::move(nextRenderer);
+		layer->shaderId = preparedProgram.shaderId;
+		layer->sourceFingerprint = preparedProgram.sourceFingerprint;
+		layer->pendingFingerprint.clear();
+	}
+}
+
+RuntimeRenderScene::LayerProgram* RuntimeRenderScene::FindLayer(const std::string& layerId)
+{
+	for (LayerProgram& layer : mLayers)
+	{
+		if (layer.layerId == layerId)
+			return &layer;
+	}
+	return nullptr;
+}
+
+const RuntimeRenderScene::LayerProgram* RuntimeRenderScene::FindLayer(const std::string& layerId) const
+{
+	for (const LayerProgram& layer : mLayers)
+	{
+		if (layer.layerId == layerId)
+			return &layer;
+	}
+	return nullptr;
+}
+
+std::string RuntimeRenderScene::Fingerprint(const RuntimeShaderArtifact& artifact)
+{
+	const std::hash<std::string> hasher;
+	return artifact.shaderId + ":" + std::to_string(artifact.fragmentShaderSource.size()) + ":" + std::to_string(hasher(artifact.fragmentShaderSource));
+}

apps/RenderCadenceCompositor/render/RuntimeRenderScene.h

@@ -0,0 +1,46 @@
+#pragma once
+
+#include "../runtime/RuntimeLayerModel.h"
+#include "RuntimeShaderPrepareWorker.h"
+#include "RuntimeShaderRenderer.h"
+
+#include <windows.h>
+
+#include <cstdint>
+#include <memory>
+#include <string>
+#include <vector>
+
+class RuntimeRenderScene
+{
+public:
+	RuntimeRenderScene() = default;
+	RuntimeRenderScene(const RuntimeRenderScene&) = delete;
+	RuntimeRenderScene& operator=(const RuntimeRenderScene&) = delete;
+	~RuntimeRenderScene();
+
+	bool StartPrepareWorker(std::unique_ptr<HiddenGlWindow> sharedWindow, std::string& error);
+	bool CommitRenderLayers(const std::vector<RenderCadenceCompositor::RuntimeRenderLayerModel>& layers, std::string& error);
+	bool HasLayers();
+	void RenderFrame(uint64_t frameIndex, unsigned width, unsigned height);
+	void ShutdownGl();
+
+private:
+	struct LayerProgram
+	{
+		std::string layerId;
+		std::string shaderId;
+		std::string sourceFingerprint;
+		std::string pendingFingerprint;
+		std::unique_ptr<RuntimeShaderRenderer> renderer;
+	};
+
+	void ConsumePreparedPrograms();
+	LayerProgram* FindLayer(const std::string& layerId);
+	const LayerProgram* FindLayer(const std::string& layerId) const;
+	static std::string Fingerprint(const RuntimeShaderArtifact& artifact);
+
+	RuntimeShaderPrepareWorker mPrepareWorker;
+	std::vector<LayerProgram> mLayers;
+	std::vector<std::string> mLayerOrder;
+};

apps/RenderCadenceCompositor/render/RuntimeShaderParams.cpp

@@ -0,0 +1,120 @@
+#include "RuntimeShaderParams.h"
+
+#include "Std140Buffer.h"
+
+#include <chrono>
+
+namespace
+{
+ShaderParameterValue DefaultValueForDefinition(const ShaderParameterDefinition& definition)
+{
+	ShaderParameterValue value;
+	switch (definition.type)
+	{
+	case ShaderParameterType::Float:
+		value.numberValues = definition.defaultNumbers.empty() ? std::vector<double>{ 0.0 } : definition.defaultNumbers;
+		break;
+	case ShaderParameterType::Vec2:
+		value.numberValues = definition.defaultNumbers.size() == 2 ? definition.defaultNumbers : std::vector<double>{ 0.0, 0.0 };
+		break;
+	case ShaderParameterType::Color:
+		value.numberValues = definition.defaultNumbers.size() == 4 ? definition.defaultNumbers : std::vector<double>{ 1.0, 1.0, 1.0, 1.0 };
+		break;
+	case ShaderParameterType::Boolean:
+		value.booleanValue = definition.defaultBoolean;
+		break;
+	case ShaderParameterType::Enum:
+		value.enumValue = definition.defaultEnumValue;
+		break;
+	case ShaderParameterType::Text:
+		value.textValue = definition.defaultTextValue;
+		break;
+	case ShaderParameterType::Trigger:
+		value.numberValues = { 0.0, -1000000.0 };
+		break;
+	}
+	return value;
+}
+
+int EnumIndexForDefault(const ShaderParameterDefinition& definition, const ShaderParameterValue& value)
+{
+	for (std::size_t optionIndex = 0; optionIndex < definition.enumOptions.size(); ++optionIndex)
+	{
+		if (definition.enumOptions[optionIndex].value == value.enumValue)
+			return static_cast<int>(optionIndex);
+	}
+	return 0;
+}
+
+double UtcSecondsOfDay()
+{
+	const auto now = std::chrono::system_clock::now();
+	const auto seconds = std::chrono::duration_cast<std::chrono::seconds>(now.time_since_epoch()).count();
+	const long long secondsPerDay = 24 * 60 * 60;
+	long long daySeconds = seconds % secondsPerDay;
+	if (daySeconds < 0)
+		daySeconds += secondsPerDay;
+	return static_cast<double>(daySeconds);
+}
+}
+
+std::vector<unsigned char> BuildRuntimeShaderGlobalParamsStd140(
+	const RuntimeShaderArtifact& artifact,
+	uint64_t frameIndex,
+	unsigned width,
+	unsigned height)
+{
+	std::vector<unsigned char> buffer;
+	buffer.reserve(512);
+
+	AppendStd140Float(buffer, static_cast<float>(frameIndex) / 60.0f);
+	AppendStd140Vec2(buffer, static_cast<float>(width), static_cast<float>(height));
+	AppendStd140Vec2(buffer, static_cast<float>(width), static_cast<float>(height));
+	AppendStd140Float(buffer, static_cast<float>(UtcSecondsOfDay()));
+	AppendStd140Float(buffer, 0.0f);
+	AppendStd140Float(buffer, 0.37f);
+	AppendStd140Float(buffer, static_cast<float>(frameIndex));
+	AppendStd140Float(buffer, 1.0f);
+	AppendStd140Float(buffer, 0.0f);
+	AppendStd140Int(buffer, 0);
+	AppendStd140Int(buffer, 0);
+	AppendStd140Int(buffer, 0);
+
+	for (const ShaderParameterDefinition& definition : artifact.parameterDefinitions)
+	{
+		const ShaderParameterValue value = DefaultValueForDefinition(definition);
+		switch (definition.type)
+		{
+		case ShaderParameterType::Float:
+			AppendStd140Float(buffer, value.numberValues.empty() ? 0.0f : static_cast<float>(value.numberValues[0]));
+			break;
+		case ShaderParameterType::Vec2:
+			AppendStd140Vec2(buffer,
+				value.numberValues.size() > 0 ? static_cast<float>(value.numberValues[0]) : 0.0f,
+				value.numberValues.size() > 1 ? static_cast<float>(value.numberValues[1]) : 0.0f);
+			break;
+		case ShaderParameterType::Color:
+			AppendStd140Vec4(buffer,
+				value.numberValues.size() > 0 ? static_cast<float>(value.numberValues[0]) : 1.0f,
+				value.numberValues.size() > 1 ? static_cast<float>(value.numberValues[1]) : 1.0f,
+				value.numberValues.size() > 2 ? static_cast<float>(value.numberValues[2]) : 1.0f,
+				value.numberValues.size() > 3 ? static_cast<float>(value.numberValues[3]) : 1.0f);
+			break;
+		case ShaderParameterType::Boolean:
+			AppendStd140Int(buffer, value.booleanValue ? 1 : 0);
+			break;
+		case ShaderParameterType::Enum:
+			AppendStd140Int(buffer, EnumIndexForDefault(definition, value));
+			break;
+		case ShaderParameterType::Text:
+			break;
+		case ShaderParameterType::Trigger:
+			AppendStd140Int(buffer, 0);
+			AppendStd140Float(buffer, -1000000.0f);
+			break;
+		}
+	}
+
+	buffer.resize(AlignStd140(buffer.size(), 16), 0);
+	return buffer;
+}

apps/RenderCadenceCompositor/render/RuntimeShaderParams.h

@@ -0,0 +1,12 @@
+#pragma once
+
+#include "../runtime/RuntimeShaderArtifact.h"
+
+#include <cstdint>
+#include <vector>
+
+std::vector<unsigned char> BuildRuntimeShaderGlobalParamsStd140(
+	const RuntimeShaderArtifact& artifact,
+	uint64_t frameIndex,
+	unsigned width,
+	unsigned height);

apps/RenderCadenceCompositor/render/RuntimeShaderPrepareWorker.cpp

@@ -0,0 +1,158 @@
+#include "RuntimeShaderPrepareWorker.h"
+
+#include "../platform/HiddenGlWindow.h"
+#include "RuntimeShaderRenderer.h"
+
+#include <algorithm>
+#include <chrono>
+#include <functional>
+#include <utility>
+
+RuntimeShaderPrepareWorker::~RuntimeShaderPrepareWorker()
+{
+	Stop();
+}
+
+bool RuntimeShaderPrepareWorker::Start(std::unique_ptr<HiddenGlWindow> sharedWindow, std::string& error)
+{
+	if (mThread.joinable())
+		return true;
+	if (!sharedWindow || sharedWindow->DeviceContext() == nullptr || sharedWindow->Context() == nullptr)
+	{
+		error = "Runtime shader prepare worker needs an existing shared GL context.";
+		return false;
+	}
+
+	mWindow = std::move(sharedWindow);
+	mStopping.store(false, std::memory_order_release);
+	mStarted.store(false, std::memory_order_release);
+	{
+		std::lock_guard<std::mutex> lock(mMutex);
+		mStartupReady = false;
+		mStartupError.clear();
+	}
+	mThread = std::thread([this]() { ThreadMain(); });
+
+	std::unique_lock<std::mutex> lock(mMutex);
+	if (!mStartupCondition.wait_for(lock, std::chrono::seconds(3), [this]() {
+		return mStartupReady || !mStartupError.empty();
+	}))
+	{
+		error = "Timed out starting runtime shader prepare worker.";
+		lock.unlock();
+		Stop();
+		return false;
+	}
+	if (!mStartupError.empty())
+	{
+		error = mStartupError;
+		lock.unlock();
+		Stop();
+		return false;
+	}
+	return true;
+}
+
+void RuntimeShaderPrepareWorker::Stop()
+{
+	mStopping.store(true, std::memory_order_release);
+	mCondition.notify_all();
+	if (mThread.joinable())
+		mThread.join();
+
+	std::deque<RuntimePreparedShaderProgram> completed;
+	{
+		std::lock_guard<std::mutex> lock(mMutex);
+		mRequests.clear();
+		completed.swap(mCompleted);
+	}
+	for (RuntimePreparedShaderProgram& program : completed)
+		program.ReleaseGl();
+	mWindow.reset();
+	mStarted.store(false, std::memory_order_release);
+}
+
+void RuntimeShaderPrepareWorker::Submit(const std::vector<RenderCadenceCompositor::RuntimeRenderLayerModel>& layers)
+{
+	std::lock_guard<std::mutex> lock(mMutex);
+	for (const RenderCadenceCompositor::RuntimeRenderLayerModel& layer : layers)
+	{
+		if (layer.artifact.fragmentShaderSource.empty())
+			continue;
+
+		PrepareRequest request;
+		request.layerId = layer.id;
+		request.shaderId = layer.shaderId;
+		request.sourceFingerprint = Fingerprint(layer.artifact);
+		request.artifact = layer.artifact;
+
+		auto sameLayer = [&request](const PrepareRequest& existing) {
+			return existing.layerId == request.layerId;
+		};
+		mRequests.erase(std::remove_if(mRequests.begin(), mRequests.end(), sameLayer), mRequests.end());
+		mRequests.push_back(std::move(request));
+	}
+	mCondition.notify_one();
+}
+
+bool RuntimeShaderPrepareWorker::TryConsume(RuntimePreparedShaderProgram& preparedProgram)
+{
+	std::lock_guard<std::mutex> lock(mMutex);
+	if (mCompleted.empty())
+		return false;
+
+	preparedProgram = std::move(mCompleted.front());
+	mCompleted.pop_front();
+	return true;
+}
+
+void RuntimeShaderPrepareWorker::ThreadMain()
+{
+	if (!mWindow || !mWindow->MakeCurrent())
+	{
+		std::lock_guard<std::mutex> lock(mMutex);
+		mStartupError = "Runtime shader prepare worker could not make shared GL context current.";
+		mStartupCondition.notify_all();
+		return;
+	}
+	{
+		std::lock_guard<std::mutex> lock(mMutex);
+		mStartupReady = true;
+	}
+	mStarted.store(true, std::memory_order_release);
+	mStartupCondition.notify_all();
+
+	while (!mStopping.load(std::memory_order_acquire))
+	{
+		PrepareRequest request;
+		{
+			std::unique_lock<std::mutex> lock(mMutex);
+			mCondition.wait(lock, [this]() {
+				return mStopping.load(std::memory_order_acquire) || !mRequests.empty();
+			});
+			if (mStopping.load(std::memory_order_acquire))
+				break;
+			request = std::move(mRequests.front());
+			mRequests.pop_front();
+		}
+
+		RuntimePreparedShaderProgram preparedProgram;
+		RuntimeShaderRenderer::BuildPreparedProgram(
+			request.layerId,
+			request.sourceFingerprint,
+			request.artifact,
+			preparedProgram);
+		glFlush();
+
+		std::lock_guard<std::mutex> lock(mMutex);
+		mCompleted.push_back(std::move(preparedProgram));
+	}
+
+	mWindow->ClearCurrent();
+}
+
+std::string RuntimeShaderPrepareWorker::Fingerprint(const RuntimeShaderArtifact& artifact)
+{
+	const std::hash<std::string> hasher;
+	return artifact.shaderId + ":" + std::to_string(artifact.fragmentShaderSource.size()) + ":" + std::to_string(hasher(artifact.fragmentShaderSource));
+}

apps/RenderCadenceCompositor/render/RuntimeShaderPrepareWorker.h

@@ -0,0 +1,56 @@
+#pragma once
+
+#include "RuntimeShaderProgram.h"
+#include "../runtime/RuntimeLayerModel.h"
+
+#include <windows.h>
+
+#include <atomic>
+#include <condition_variable>
+#include <deque>
+#include <memory>
+#include <mutex>
+#include <string>
+#include <thread>
+#include <vector>
+
+class HiddenGlWindow;
+
+class RuntimeShaderPrepareWorker
+{
+public:
+	RuntimeShaderPrepareWorker() = default;
+	RuntimeShaderPrepareWorker(const RuntimeShaderPrepareWorker&) = delete;
+	RuntimeShaderPrepareWorker& operator=(const RuntimeShaderPrepareWorker&) = delete;
+	~RuntimeShaderPrepareWorker();
+
+	bool Start(std::unique_ptr<HiddenGlWindow> sharedWindow, std::string& error);
+	void Stop();
+
+	void Submit(const std::vector<RenderCadenceCompositor::RuntimeRenderLayerModel>& layers);
+	bool TryConsume(RuntimePreparedShaderProgram& preparedProgram);
+
+private:
+	struct PrepareRequest
+	{
+		std::string layerId;
+		std::string shaderId;
+		std::string sourceFingerprint;
+		RuntimeShaderArtifact artifact;
+	};
+
+	void ThreadMain();
+	static std::string Fingerprint(const RuntimeShaderArtifact& artifact);
+
+	std::unique_ptr<HiddenGlWindow> mWindow;
+	std::mutex mMutex;
+	std::condition_variable mCondition;
+	std::deque<PrepareRequest> mRequests;
+	std::deque<RuntimePreparedShaderProgram> mCompleted;
+	std::condition_variable mStartupCondition;
+	std::thread mThread;
+	std::atomic<bool> mStopping{ false };
+	std::atomic<bool> mStarted{ false };
+	bool mStartupReady = false;
+	std::string mStartupError;
+};

apps/RenderCadenceCompositor/render/RuntimeShaderProgram.h

@@ -0,0 +1,32 @@
+#pragma once
+
+#include "GLExtensions.h"
+#include "../runtime/RuntimeShaderArtifact.h"
+
+#include <string>
+
+struct RuntimePreparedShaderProgram
+{
+	std::string layerId;
+	std::string shaderId;
+	std::string sourceFingerprint;
+	RuntimeShaderArtifact artifact;
+	GLuint program = 0;
+	GLuint vertexShader = 0;
+	GLuint fragmentShader = 0;
+	bool succeeded = false;
+	std::string error;
+
+	void ReleaseGl()
+	{
+		if (program != 0)
+			glDeleteProgram(program);
+		if (vertexShader != 0)
+			glDeleteShader(vertexShader);
+		if (fragmentShader != 0)
+			glDeleteShader(fragmentShader);
+		program = 0;
+		vertexShader = 0;
+		fragmentShader = 0;
+	}
+};

apps/RenderCadenceCompositor/render/RuntimeShaderRenderer.cpp

@@ -0,0 +1,323 @@
+#include "RuntimeShaderRenderer.h"
+
+#include "RuntimeShaderParams.h"
+
+#include <array>
+#include <cstring>
+#include <string>
+
+namespace
+{
+constexpr GLuint kGlobalParamsBindingPoint = 0;
+constexpr GLuint kSourceTextureUnit = 0;
+
+const char* kVertexShaderSource = R"GLSL(
+#version 430 core
+out vec2 vTexCoord;
+void main()
+{
+	vec2 positions[3] = vec2[3](
+		vec2(-1.0, -1.0),
+		vec2( 3.0, -1.0),
+		vec2(-1.0,  3.0));
+	vec2 texCoords[3] = vec2[3](
+		vec2(0.0, 0.0),
+		vec2(2.0, 0.0),
+		vec2(0.0, 2.0));
+	gl_Position = vec4(positions[gl_VertexID], 0.0, 1.0);
+	vTexCoord = texCoords[gl_VertexID];
+}
+)GLSL";
+
+}
+
+RuntimeShaderRenderer::~RuntimeShaderRenderer()
+{
+	ShutdownGl();
+}
+
+bool RuntimeShaderRenderer::CommitFragmentShader(const std::string& fragmentShaderSource, std::string& error)
+{
+	RuntimeShaderArtifact artifact;
+	artifact.shaderId = "runtime-fragment";
+	artifact.displayName = "Runtime Fragment";
+	artifact.fragmentShaderSource = fragmentShaderSource;
+	return CommitShaderArtifact(artifact, error);
+}
+
+bool RuntimeShaderRenderer::CommitShaderArtifact(const RuntimeShaderArtifact& artifact, std::string& error)
+{
+	if (artifact.fragmentShaderSource.empty())
+	{
+		error = "Cannot commit an empty fragment shader.";
+		return false;
+	}
+
+	if (!EnsureStaticGlResources(error))
+		return false;
+
+	GLuint vertexShader = 0;
+	GLuint fragmentShader = 0;
+	GLuint program = 0;
+	if (!BuildProgram(artifact.fragmentShaderSource, program, vertexShader, fragmentShader, error))
+		return false;
+
+	DestroyProgram();
+	mProgram = program;
+	mVertexShader = vertexShader;
+	mFragmentShader = fragmentShader;
+	mArtifact = artifact;
+	AssignSamplerUniforms(mProgram);
+	return true;
+}
+
+bool RuntimeShaderRenderer::CommitPreparedProgram(RuntimePreparedShaderProgram& preparedProgram, std::string& error)
+{
+	if (!preparedProgram.succeeded || preparedProgram.program == 0)
+	{
+		error = preparedProgram.error.empty() ? "Prepared runtime shader program is not valid." : preparedProgram.error;
+		return false;
+	}
+
+	if (!EnsureStaticGlResources(error))
+		return false;
+
+	DestroyProgram();
+	mProgram = preparedProgram.program;
+	mVertexShader = preparedProgram.vertexShader;
+	mFragmentShader = preparedProgram.fragmentShader;
+	mArtifact = preparedProgram.artifact;
+	preparedProgram.program = 0;
+	preparedProgram.vertexShader = 0;
+	preparedProgram.fragmentShader = 0;
+	return true;
+}
+
+bool RuntimeShaderRenderer::BuildPreparedProgram(
+	const std::string& layerId,
+	const std::string& sourceFingerprint,
+	const RuntimeShaderArtifact& artifact,
+	RuntimePreparedShaderProgram& preparedProgram)
+{
+	preparedProgram = RuntimePreparedShaderProgram();
+	preparedProgram.layerId = layerId;
+	preparedProgram.shaderId = artifact.shaderId;
+	preparedProgram.sourceFingerprint = sourceFingerprint;
+	preparedProgram.artifact = artifact;
+
+	if (artifact.fragmentShaderSource.empty())
+	{
+		preparedProgram.error = "Cannot prepare an empty fragment shader.";
+		return false;
+	}
+
+	if (!BuildProgram(
+		artifact.fragmentShaderSource,
+		preparedProgram.program,
+		preparedProgram.vertexShader,
+		preparedProgram.fragmentShader,
+		preparedProgram.error))
+	{
+		preparedProgram.ReleaseGl();
+		return false;
+	}
+
+	preparedProgram.succeeded = true;
+	AssignSamplerUniforms(preparedProgram.program);
+	return true;
+}
+
+void RuntimeShaderRenderer::RenderFrame(uint64_t frameIndex, unsigned width, unsigned height)
+{
+	if (mProgram == 0)
+		return;
+
+	glViewport(0, 0, static_cast<GLsizei>(width), static_cast<GLsizei>(height));
+	glDisable(GL_SCISSOR_TEST);
+	glDisable(GL_DEPTH_TEST);
+	glDisable(GL_BLEND);
+	UpdateGlobalParams(frameIndex, width, height);
+	BindRuntimeTextures();
+	glBindVertexArray(mVertexArray);
+	glUseProgram(mProgram);
+	glDrawArrays(GL_TRIANGLES, 0, 3);
+	glUseProgram(0);
+	glBindVertexArray(0);
+}
+
+void RuntimeShaderRenderer::ShutdownGl()
+{
+	DestroyProgram();
+	DestroyStaticGlResources();
+}
+
+bool RuntimeShaderRenderer::EnsureStaticGlResources(std::string& error)
+{
+	if (mVertexArray == 0)
+		glGenVertexArrays(1, &mVertexArray);
+	if (mGlobalParamsBuffer == 0)
+	{
+		glGenBuffers(1, &mGlobalParamsBuffer);
+		glBindBuffer(GL_UNIFORM_BUFFER, mGlobalParamsBuffer);
+		glBufferData(GL_UNIFORM_BUFFER, 1024, nullptr, GL_DYNAMIC_DRAW);
+		glBindBuffer(GL_UNIFORM_BUFFER, 0);
+	}
+	if (mFallbackSourceTexture == 0)
+	{
+		const unsigned char pixels[] = {
+			0, 0, 0, 255,
+			96, 64, 32, 255,
+			64, 96, 160, 255,
+			255, 255, 255, 255
+		};
+		glGenTextures(1, &mFallbackSourceTexture);
+		glBindTexture(GL_TEXTURE_2D, mFallbackSourceTexture);
+		glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_LINEAR);
+		glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MAG_FILTER, GL_LINEAR);
+		glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_S, GL_CLAMP_TO_EDGE);
+		glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_T, GL_CLAMP_TO_EDGE);
+		glTexImage2D(GL_TEXTURE_2D, 0, GL_RGBA8, 2, 2, 0, GL_BGRA, GL_UNSIGNED_BYTE, pixels);
+		glBindTexture(GL_TEXTURE_2D, 0);
+	}
+
+	if (mVertexArray == 0 || mGlobalParamsBuffer == 0 || mFallbackSourceTexture == 0)
+	{
+		error = "Failed to create runtime shader GL resources.";
+		return false;
+	}
+	return true;
+}
+
+bool RuntimeShaderRenderer::BuildProgram(const std::string& fragmentShaderSource, GLuint& program, GLuint& vertexShader, GLuint& fragmentShader, std::string& error)
+{
+	program = 0;
+	vertexShader = 0;
+	fragmentShader = 0;
+
+	if (!CompileShader(GL_VERTEX_SHADER, kVertexShaderSource, vertexShader, error))
+		return false;
+	if (!CompileShader(GL_FRAGMENT_SHADER, fragmentShaderSource.c_str(), fragmentShader, error))
+	{
+		glDeleteShader(vertexShader);
+		vertexShader = 0;
+		return false;
+	}
+
+	program = glCreateProgram();
+	glAttachShader(program, vertexShader);
+	glAttachShader(program, fragmentShader);
+	glLinkProgram(program);
+
+	GLint linkResult = GL_FALSE;
+	glGetProgramiv(program, GL_LINK_STATUS, &linkResult);
+	if (linkResult == GL_FALSE)
+	{
+		std::array<char, 4096> log = {};
+		GLsizei length = 0;
+		glGetProgramInfoLog(program, static_cast<GLsizei>(log.size()), &length, log.data());
+		error = std::string(log.data(), static_cast<std::size_t>(length));
+		glDeleteProgram(program);
+		glDeleteShader(vertexShader);
+		glDeleteShader(fragmentShader);
+		program = 0;
+		vertexShader = 0;
+		fragmentShader = 0;
+		return false;
+	}
+
+	const GLuint globalParamsIndex = glGetUniformBlockIndex(program, "GlobalParams");
+	if (globalParamsIndex != GL_INVALID_INDEX)
+		glUniformBlockBinding(program, globalParamsIndex, kGlobalParamsBindingPoint);
+	return true;
+}
+
+void RuntimeShaderRenderer::AssignSamplerUniforms(GLuint program)
+{
+	glUseProgram(program);
+	const GLint videoInputLocation = glGetUniformLocation(program, "gVideoInput");
+	if (videoInputLocation >= 0)
+		glUniform1i(videoInputLocation, static_cast<GLint>(kSourceTextureUnit));
+	const GLint videoInputArrayLocation = glGetUniformLocation(program, "gVideoInput_0");
+	if (videoInputArrayLocation >= 0)
+		glUniform1i(videoInputArrayLocation, static_cast<GLint>(kSourceTextureUnit));
+	const GLint layerInputLocation = glGetUniformLocation(program, "gLayerInput");
+	if (layerInputLocation >= 0)
+		glUniform1i(layerInputLocation, static_cast<GLint>(kSourceTextureUnit));
+	const GLint layerInputArrayLocation = glGetUniformLocation(program, "gLayerInput_0");
+	if (layerInputArrayLocation >= 0)
+		glUniform1i(layerInputArrayLocation, static_cast<GLint>(kSourceTextureUnit));
+	glUseProgram(0);
+}
+
+void RuntimeShaderRenderer::UpdateGlobalParams(uint64_t frameIndex, unsigned width, unsigned height)
+{
+	std::vector<unsigned char>& buffer = mGlobalParamsScratch;
+	buffer = BuildRuntimeShaderGlobalParamsStd140(mArtifact, frameIndex, width, height);
+	glBindBuffer(GL_UNIFORM_BUFFER, mGlobalParamsBuffer);
+	const GLsizeiptr bufferSize = static_cast<GLsizeiptr>(buffer.size());
+	if (mGlobalParamsBufferSize != bufferSize)
+	{
+		glBufferData(GL_UNIFORM_BUFFER, bufferSize, buffer.data(), GL_DYNAMIC_DRAW);
+		mGlobalParamsBufferSize = bufferSize;
+	}
+	else
+	{
+		glBufferSubData(GL_UNIFORM_BUFFER, 0, bufferSize, buffer.data());
+	}
+	glBindBufferBase(GL_UNIFORM_BUFFER, kGlobalParamsBindingPoint, mGlobalParamsBuffer);
+	glBindBuffer(GL_UNIFORM_BUFFER, 0);
+}
+
+void RuntimeShaderRenderer::BindRuntimeTextures()
+{
+	glActiveTexture(GL_TEXTURE0 + kSourceTextureUnit);
+	glBindTexture(GL_TEXTURE_2D, mFallbackSourceTexture);
+	glActiveTexture(GL_TEXTURE0);
+}
+
+bool RuntimeShaderRenderer::CompileShader(GLenum shaderType, const char* source, GLuint& shader, std::string& error)
+{
+	shader = glCreateShader(shaderType);
+	glShaderSource(shader, 1, &source, nullptr);
+	glCompileShader(shader);
+
+	GLint compileResult = GL_FALSE;
+	glGetShaderiv(shader, GL_COMPILE_STATUS, &compileResult);
+	if (compileResult != GL_FALSE)
+		return true;
+
+	std::array<char, 4096> log = {};
+	GLsizei length = 0;
+	glGetShaderInfoLog(shader, static_cast<GLsizei>(log.size()), &length, log.data());
+	error = std::string(log.data(), static_cast<std::size_t>(length));
+	glDeleteShader(shader);
+	shader = 0;
+	return false;
+}
+
+void RuntimeShaderRenderer::DestroyProgram()
+{
+	if (mProgram != 0)
+		glDeleteProgram(mProgram);
+	if (mVertexShader != 0)
+		glDeleteShader(mVertexShader);
+	if (mFragmentShader != 0)
+		glDeleteShader(mFragmentShader);
+	mProgram = 0;
+	mVertexShader = 0;
+	mFragmentShader = 0;
+}
+
+void RuntimeShaderRenderer::DestroyStaticGlResources()
+{
+	if (mGlobalParamsBuffer != 0)
+		glDeleteBuffers(1, &mGlobalParamsBuffer);
+	if (mVertexArray != 0)
+		glDeleteVertexArrays(1, &mVertexArray);
+	if (mFallbackSourceTexture != 0)
+		glDeleteTextures(1, &mFallbackSourceTexture);
+	mGlobalParamsBuffer = 0;
+	mGlobalParamsBufferSize = 0;
+	mVertexArray = 0;
+	mFallbackSourceTexture = 0;
+}

apps/RenderCadenceCompositor/render/RuntimeShaderRenderer.h

@@ -0,0 +1,51 @@
+#pragma once
+
+#include "GLExtensions.h"
+#include "RuntimeShaderProgram.h"
+#include "../runtime/RuntimeShaderArtifact.h"
+
+#include <cstdint>
+#include <string>
+#include <vector>
+
+class RuntimeShaderRenderer
+{
+public:
+	RuntimeShaderRenderer() = default;
+	RuntimeShaderRenderer(const RuntimeShaderRenderer&) = delete;
+	RuntimeShaderRenderer& operator=(const RuntimeShaderRenderer&) = delete;
+	~RuntimeShaderRenderer();
+
+	bool CommitFragmentShader(const std::string& fragmentShaderSource, std::string& error);
+	bool CommitShaderArtifact(const RuntimeShaderArtifact& artifact, std::string& error);
+	bool CommitPreparedProgram(RuntimePreparedShaderProgram& preparedProgram, std::string& error);
+	bool HasProgram() const { return mProgram != 0; }
+	void RenderFrame(uint64_t frameIndex, unsigned width, unsigned height);
+	void ShutdownGl();
+
+	static bool BuildPreparedProgram(
+		const std::string& layerId,
+		const std::string& sourceFingerprint,
+		const RuntimeShaderArtifact& artifact,
+		RuntimePreparedShaderProgram& preparedProgram);
+
+private:
+	bool EnsureStaticGlResources(std::string& error);
+	static bool CompileShader(GLenum shaderType, const char* source, GLuint& shader, std::string& error);
+	static bool BuildProgram(const std::string& fragmentShaderSource, GLuint& program, GLuint& vertexShader, GLuint& fragmentShader, std::string& error);
+	static void AssignSamplerUniforms(GLuint program);
+	void UpdateGlobalParams(uint64_t frameIndex, unsigned width, unsigned height);
+	void BindRuntimeTextures();
+	void DestroyProgram();
+	void DestroyStaticGlResources();
+
+	RuntimeShaderArtifact mArtifact;
+	GLuint mProgram = 0;
+	GLuint mVertexShader = 0;
+	GLuint mFragmentShader = 0;
+	GLuint mVertexArray = 0;
+	GLuint mGlobalParamsBuffer = 0;
+	GLsizeiptr mGlobalParamsBufferSize = 0;
+	GLuint mFallbackSourceTexture = 0;
+	std::vector<unsigned char> mGlobalParamsScratch;
+};

apps/RenderCadenceCompositor/render/SimpleMotionRenderer.cpp

@@ -0,0 +1,50 @@
+#include "SimpleMotionRenderer.h"
+
+#include "GLExtensions.h"
+
+#include <algorithm>
+#include <cmath>
+
+bool SimpleMotionRenderer::InitializeGl(unsigned width, unsigned height)
+{
+	mWidth = width;
+	mHeight = height;
+	return mWidth > 0 && mHeight > 0;
+}
+
+void SimpleMotionRenderer::RenderFrame(uint64_t frameIndex)
+{
+	const float t = static_cast<float>(frameIndex) / 60.0f;
+	const float red = 0.1f + 0.4f * (0.5f + 0.5f * std::sin(t));
+	const float green = 0.1f + 0.4f * (0.5f + 0.5f * std::sin(t * 0.73f + 1.0f));
+	const float blue = 0.15f + 0.3f * (0.5f + 0.5f * std::sin(t * 0.41f + 2.0f));
+
+	glViewport(0, 0, static_cast<GLsizei>(mWidth), static_cast<GLsizei>(mHeight));
+	glDisable(GL_SCISSOR_TEST);
+	glClearColor(red, green, blue, 1.0f);
+	glClear(GL_COLOR_BUFFER_BIT);
+
+	const int boxWidth = (std::max)(1, static_cast<int>(mWidth / 6));
+	const int boxHeight = (std::max)(1, static_cast<int>(mHeight / 5));
+	const float phase = 0.5f + 0.5f * std::sin(t * 1.7f);
+	const int x = static_cast<int>(phase * static_cast<float>(mWidth - static_cast<unsigned>(boxWidth)));
+	const int y = static_cast<int>((0.5f + 0.5f * std::sin(t * 1.1f + 0.8f)) * static_cast<float>(mHeight - static_cast<unsigned>(boxHeight)));
+
+	glEnable(GL_SCISSOR_TEST);
+	glScissor(x, y, boxWidth, boxHeight);
+	glClearColor(1.0f - red, 0.85f, 0.15f + blue, 1.0f);
+	glClear(GL_COLOR_BUFFER_BIT);
+
+	const int stripeWidth = (std::max)(1, static_cast<int>(mWidth / 80));
+	const int stripeX = static_cast<int>((frameIndex % 120) * (mWidth - static_cast<unsigned>(stripeWidth)) / 119);
+	glScissor(stripeX, 0, stripeWidth, static_cast<GLsizei>(mHeight));
+	glClearColor(1.0f, 1.0f, 1.0f, 1.0f);
+	glClear(GL_COLOR_BUFFER_BIT);
+	glDisable(GL_SCISSOR_TEST);
+}
+
+void SimpleMotionRenderer::ShutdownGl()
+{
+	mWidth = 0;
+	mHeight = 0;
+}

apps/RenderCadenceCompositor/render/SimpleMotionRenderer.h

@@ -0,0 +1,20 @@
+#pragma once
+
+#include <cstdint>
+
+class SimpleMotionRenderer
+{
+public:
+	SimpleMotionRenderer() = default;
+
+	bool InitializeGl(unsigned width, unsigned height);
+	void RenderFrame(uint64_t frameIndex);
+	void ShutdownGl();
+
+	unsigned Width() const { return mWidth; }
+	unsigned Height() const { return mHeight; }
+
+private:
+	unsigned mWidth = 0;
+	unsigned mHeight = 0;
+};

apps/RenderCadenceCompositor/runtime/RuntimeLayerModel.cpp

@@ -0,0 +1,224 @@
+#include "RuntimeLayerModel.h"
+
+#include <utility>
+
+namespace RenderCadenceCompositor
+{
+bool RuntimeLayerModel::InitializeSingleLayer(const SupportedShaderCatalog& shaderCatalog, const std::string& shaderId, std::string& error)
+{
+	Clear();
+	if (shaderId.empty())
+	{
+		error.clear();
+		return true;
+	}
+
+	const ShaderPackage* shaderPackage = shaderCatalog.FindPackage(shaderId);
+	if (!shaderPackage)
+	{
+		error = "Shader '" + shaderId + "' is not in the supported shader catalog.";
+		return false;
+	}
+
+	Layer layer;
+	layer.id = AllocateLayerId();
+	layer.shaderId = shaderPackage->id;
+	layer.shaderName = shaderPackage->displayName.empty() ? shaderPackage->id : shaderPackage->displayName;
+	layer.buildState = RuntimeLayerBuildState::Pending;
+	layer.message = "Runtime Slang build is waiting to start.";
+	mLayers.push_back(std::move(layer));
+	error.clear();
+	return true;
+}
+
+bool RuntimeLayerModel::AddLayer(const SupportedShaderCatalog& shaderCatalog, const std::string& shaderId, std::string& layerId, std::string& error)
+{
+	const ShaderPackage* shaderPackage = shaderCatalog.FindPackage(shaderId);
+	if (!shaderPackage)
+	{
+		error = "Shader '" + shaderId + "' is not in the supported shader catalog.";
+		return false;
+	}
+
+	Layer layer;
+	layer.id = AllocateLayerId();
+	layer.shaderId = shaderPackage->id;
+	layer.shaderName = shaderPackage->displayName.empty() ? shaderPackage->id : shaderPackage->displayName;
+	layer.buildState = RuntimeLayerBuildState::Pending;
+	layer.message = "Runtime Slang build is waiting to start.";
+	layerId = layer.id;
+	mLayers.push_back(std::move(layer));
+	error.clear();
+	return true;
+}
+
+bool RuntimeLayerModel::RemoveLayer(const std::string& layerId, std::string& error)
+{
+	for (auto layerIt = mLayers.begin(); layerIt != mLayers.end(); ++layerIt)
+	{
+		if (layerIt->id != layerId)
+			continue;
+
+		mLayers.erase(layerIt);
+		error.clear();
+		return true;
+	}
+
+	error = "Unknown runtime layer id: " + layerId;
+	return false;
+}
+
+void RuntimeLayerModel::Clear()
+{
+	mLayers.clear();
+}
+
+bool RuntimeLayerModel::MarkBuildStarted(const std::string& layerId, const std::string& message, std::string& error)
+{
+	Layer* layer = FindLayer(layerId);
+	if (!layer)
+	{
+		error = "Unknown runtime layer id: " + layerId;
+		return false;
+	}
+
+	layer->buildState = RuntimeLayerBuildState::Pending;
+	layer->message = message;
+	layer->renderReady = false;
+	layer->artifact = RuntimeShaderArtifact();
+	error.clear();
+	return true;
+}
+
+bool RuntimeLayerModel::MarkBuildReady(const RuntimeShaderArtifact& artifact, std::string& error)
+{
+	Layer* layer = artifact.layerId.empty() ? FindFirstLayerForShader(artifact.shaderId) : FindLayer(artifact.layerId);
+	if (!layer)
+	{
+		error = artifact.layerId.empty()
+			? "No runtime layer is waiting for shader artifact: " + artifact.shaderId
+			: "No runtime layer is waiting for shader artifact on layer: " + artifact.layerId;
+		return false;
+	}
+
+	layer->shaderName = artifact.displayName.empty() ? artifact.shaderId : artifact.displayName;
+	layer->buildState = RuntimeLayerBuildState::Ready;
+	layer->message = artifact.message;
+	layer->renderReady = true;
+	layer->artifact = artifact;
+	error.clear();
+	return true;
+}
+
+bool RuntimeLayerModel::MarkBuildFailedForShader(const std::string& shaderId, const std::string& message)
+{
+	Layer* layer = FindFirstLayerForShader(shaderId);
+	if (!layer)
+		return false;
+
+	std::string error;
+	return MarkBuildFailed(layer->id, message, error);
+}
+
+bool RuntimeLayerModel::MarkBuildFailed(const std::string& layerId, const std::string& message, std::string& error)
+{
+	Layer* layer = FindLayer(layerId);
+	if (!layer)
+	{
+		error = "Unknown runtime layer id: " + layerId;
+		return false;
+	}
+
+	layer->buildState = RuntimeLayerBuildState::Failed;
+	layer->message = message;
+	layer->renderReady = false;
+	layer->artifact = RuntimeShaderArtifact();
+	error.clear();
+	return true;
+}
+
+bool RuntimeLayerModel::MarkRenderCommitFailed(const std::string& layerId, const std::string& message, std::string& error)
+{
+	return MarkBuildFailed(layerId, message, error);
+}
+
+RuntimeLayerModelSnapshot RuntimeLayerModel::Snapshot() const
+{
+	RuntimeLayerModelSnapshot snapshot;
+	snapshot.compileSucceeded = true;
+
+	for (const Layer& layer : mLayers)
+	{
+		snapshot.displayLayers.push_back(ToReadModel(layer));
+		if (!layer.message.empty() && snapshot.compileMessage.empty())
+			snapshot.compileMessage = layer.message;
+		if (layer.buildState == RuntimeLayerBuildState::Failed)
+			snapshot.compileSucceeded = false;
+		if (layer.renderReady)
+		{
+			RuntimeRenderLayerModel renderLayer;
+			renderLayer.id = layer.id;
+			renderLayer.shaderId = layer.shaderId;
+			renderLayer.artifact = layer.artifact;
+			snapshot.renderLayers.push_back(std::move(renderLayer));
+		}
+	}
+
+	if (snapshot.compileMessage.empty())
+		snapshot.compileMessage = mLayers.empty() ? "Runtime shader build disabled." : "Runtime shader build has not completed yet.";
+	return snapshot;
+}
+
+std::string RuntimeLayerModel::FirstLayerId() const
+{
+	return mLayers.empty() ? std::string() : mLayers.front().id;
+}
+
+RuntimeLayerModel::Layer* RuntimeLayerModel::FindLayer(const std::string& layerId)
+{
+	for (Layer& layer : mLayers)
+	{
+		if (layer.id == layerId)
+			return &layer;
+	}
+	return nullptr;
+}
+
+const RuntimeLayerModel::Layer* RuntimeLayerModel::FindLayer(const std::string& layerId) const
+{
+	for (const Layer& layer : mLayers)
+	{
+		if (layer.id == layerId)
+			return &layer;
+	}
+	return nullptr;
+}
+
+RuntimeLayerModel::Layer* RuntimeLayerModel::FindFirstLayerForShader(const std::string& shaderId)
+{
+	for (Layer& layer : mLayers)
+	{
+		if (layer.shaderId == shaderId)
+			return &layer;
+	}
+	return nullptr;
+}
+
+std::string RuntimeLayerModel::AllocateLayerId()
+{
+	return "runtime-layer-" + std::to_string(mNextLayerNumber++);
+}
+
+RuntimeLayerReadModel RuntimeLayerModel::ToReadModel(const Layer& layer)
+{
+	RuntimeLayerReadModel readModel;
+	readModel.id = layer.id;
+	readModel.shaderId = layer.shaderId;
+	readModel.shaderName = layer.shaderName;
+	readModel.bypass = layer.bypass;
+	readModel.buildState = layer.buildState;
+	readModel.message = layer.message;
+	readModel.renderReady = layer.renderReady;
+	return readModel;
+}
+}

apps/RenderCadenceCompositor/runtime/RuntimeLayerModel.h

@@ -0,0 +1,84 @@
+#pragma once
+
+#include "RuntimeShaderArtifact.h"
+#include "SupportedShaderCatalog.h"
+
+#include <cstdint>
+#include <string>
+#include <vector>
+
+namespace RenderCadenceCompositor
+{
+enum class RuntimeLayerBuildState
+{
+	Pending,
+	Ready,
+	Failed
+};
+
+struct RuntimeLayerReadModel
+{
+	std::string id;
+	std::string shaderId;
+	std::string shaderName;
+	bool bypass = false;
+	RuntimeLayerBuildState buildState = RuntimeLayerBuildState::Pending;
+	std::string message;
+	bool renderReady = false;
+};
+
+struct RuntimeRenderLayerModel
+{
+	std::string id;
+	std::string shaderId;
+	RuntimeShaderArtifact artifact;
+};
+
+struct RuntimeLayerModelSnapshot
+{
+	bool compileSucceeded = true;
+	std::string compileMessage;
+	std::vector<RuntimeLayerReadModel> displayLayers;
+	std::vector<RuntimeRenderLayerModel> renderLayers;
+};
+
+class RuntimeLayerModel
+{
+public:
+	bool InitializeSingleLayer(const SupportedShaderCatalog& shaderCatalog, const std::string& shaderId, std::string& error);
+	void Clear();
+
+	bool AddLayer(const SupportedShaderCatalog& shaderCatalog, const std::string& shaderId, std::string& layerId, std::string& error);
+	bool RemoveLayer(const std::string& layerId, std::string& error);
+	bool MarkBuildStarted(const std::string& layerId, const std::string& message, std::string& error);
+	bool MarkBuildReady(const RuntimeShaderArtifact& artifact, std::string& error);
+	bool MarkBuildFailedForShader(const std::string& shaderId, const std::string& message);
+	bool MarkBuildFailed(const std::string& layerId, const std::string& message, std::string& error);
+	bool MarkRenderCommitFailed(const std::string& layerId, const std::string& message, std::string& error);
+
+	RuntimeLayerModelSnapshot Snapshot() const;
+	std::string FirstLayerId() const;
+
+private:
+	struct Layer
+	{
+		std::string id;
+		std::string shaderId;
+		std::string shaderName;
+		bool bypass = false;
+		RuntimeLayerBuildState buildState = RuntimeLayerBuildState::Pending;
+		std::string message;
+		bool renderReady = false;
+		RuntimeShaderArtifact artifact;
+	};
+
+	Layer* FindLayer(const std::string& layerId);
+	const Layer* FindLayer(const std::string& layerId) const;
+	Layer* FindFirstLayerForShader(const std::string& shaderId);
+	std::string AllocateLayerId();
+	static RuntimeLayerReadModel ToReadModel(const Layer& layer);
+
+	std::vector<Layer> mLayers;
+	uint64_t mNextLayerNumber = 1;
+};
+}

apps/RenderCadenceCompositor/runtime/RuntimeShaderArtifact.h

@@ -0,0 +1,16 @@
+#pragma once
+
+#include "ShaderTypes.h"
+
+#include <string>
+#include <vector>
+
+struct RuntimeShaderArtifact
+{
+	std::string layerId;
+	std::string shaderId;
+	std::string displayName;
+	std::string fragmentShaderSource;
+	std::string message;
+	std::vector<ShaderParameterDefinition> parameterDefinitions;
+};

apps/RenderCadenceCompositor/runtime/RuntimeShaderBridge.cpp

@@ -0,0 +1,75 @@
+#include "RuntimeShaderBridge.h"
+
+#include <chrono>
+
+RuntimeShaderBridge::~RuntimeShaderBridge()
+{
+	Stop();
+}
+
+void RuntimeShaderBridge::Start(const std::string& shaderId, ArtifactCallback onArtifactReady, ErrorCallback onError)
+{
+	Start(std::string(), shaderId, std::move(onArtifactReady), std::move(onError));
+}
+
+void RuntimeShaderBridge::Start(const std::string& layerId, const std::string& shaderId, ArtifactCallback onArtifactReady, ErrorCallback onError)
+{
+	Stop();
+	if (shaderId.empty())
+		return;
+
+	mLayerId = layerId;
+	mOnArtifactReady = std::move(onArtifactReady);
+	mOnError = std::move(onError);
+	mStopping.store(false, std::memory_order_release);
+	mFinished.store(false, std::memory_order_release);
+	mCompiler.StartShaderBuild(shaderId);
+	mThread = std::thread([this]() { ThreadMain(); });
+}
+
+void RuntimeShaderBridge::RequestStop()
+{
+	mStopping.store(true, std::memory_order_release);
+}
+
+void RuntimeShaderBridge::Stop()
+{
+	RequestStop();
+	if (mThread.joinable())
+		mThread.join();
+	mCompiler.Stop();
+	mLayerId.clear();
+	mOnArtifactReady = ArtifactCallback();
+	mOnError = ErrorCallback();
+	mFinished.store(true, std::memory_order_release);
+}
+
+bool RuntimeShaderBridge::CanStopWithoutWaiting() const
+{
+	return mFinished.load(std::memory_order_acquire) && !mCompiler.Running();
+}
+
+void RuntimeShaderBridge::ThreadMain()
+{
+	while (!mStopping.load(std::memory_order_acquire))
+	{
+		RuntimeSlangShaderBuild build;
+		if (mCompiler.TryConsume(build))
+		{
+			if (build.succeeded)
+			{
+				build.artifact.layerId = mLayerId;
+				if (mOnArtifactReady)
+					mOnArtifactReady(build.artifact);
+			}
+			else if (mOnError)
+			{
+				mOnError(build.message);
+			}
+			mFinished.store(true, std::memory_order_release);
+			return;
+		}
+		std::this_thread::sleep_for(std::chrono::milliseconds(5));
+	}
+	mFinished.store(true, std::memory_order_release);
+}

apps/RenderCadenceCompositor/runtime/RuntimeShaderBridge.h

@@ -0,0 +1,38 @@
+#pragma once
+
+#include "RuntimeShaderArtifact.h"
+#include "RuntimeSlangShaderCompiler.h"
+
+#include <atomic>
+#include <functional>
+#include <string>
+#include <thread>
+
+class RuntimeShaderBridge
+{
+public:
+	using ArtifactCallback = std::function<void(const RuntimeShaderArtifact&)>;
+	using ErrorCallback = std::function<void(const std::string&)>;
+
+	RuntimeShaderBridge() = default;
+	RuntimeShaderBridge(const RuntimeShaderBridge&) = delete;
+	RuntimeShaderBridge& operator=(const RuntimeShaderBridge&) = delete;
+	~RuntimeShaderBridge();
+
+	void Start(const std::string& shaderId, ArtifactCallback onArtifactReady, ErrorCallback onError);
+	void Start(const std::string& layerId, const std::string& shaderId, ArtifactCallback onArtifactReady, ErrorCallback onError);
+	void RequestStop();
+	void Stop();
+	bool CanStopWithoutWaiting() const;
+
+private:
+	void ThreadMain();
+
+	RuntimeSlangShaderCompiler mCompiler;
+	std::thread mThread;
+	std::atomic<bool> mStopping{ false };
+	std::atomic<bool> mFinished{ true };
+	std::string mLayerId;
+	ArtifactCallback mOnArtifactReady;
+	ErrorCallback mOnError;
+};

apps/RenderCadenceCompositor/runtime/RuntimeSlangShaderCompiler.cpp

@@ -0,0 +1,148 @@
+#include "RuntimeSlangShaderCompiler.h"
+
+#include "ShaderCompiler.h"
+#include "ShaderPackageRegistry.h"
+#include "ShaderTypes.h"
+#include "SupportedShaderCatalog.h"
+
+#include <chrono>
+#include <filesystem>
+
+namespace
+{
+std::filesystem::path FindRepoRoot()
+{
+	std::filesystem::path current = std::filesystem::current_path();
+	for (;;)
+	{
+		if (std::filesystem::exists(current / "shaders" / "happy-accident" / "shader.slang") &&
+			std::filesystem::exists(current / "runtime" / "templates" / "shader_wrapper.slang.in"))
+		{
+			return current;
+		}
+
+		const std::filesystem::path parent = current.parent_path();
+		if (parent.empty() || parent == current)
+			return std::filesystem::current_path();
+		current = parent;
+	}
+}
+
+}
+
+RuntimeSlangShaderCompiler::~RuntimeSlangShaderCompiler()
+{
+	Stop();
+}
+
+void RuntimeSlangShaderCompiler::StartHappyAccidentBuild()
+{
+	StartShaderBuild("happy-accident");
+}
+
+void RuntimeSlangShaderCompiler::StartShaderBuild(const std::string& shaderId)
+{
+	if (mRunning.load(std::memory_order_acquire))
+		return;
+
+	if (mThread.joinable())
+		mThread.join();
+
+	{
+		std::lock_guard<std::mutex> lock(mMutex);
+		mReadyBuild = RuntimeSlangShaderBuild();
+	}
+
+	mRunning.store(true, std::memory_order_release);
+	mThread = std::thread([this, shaderId]() {
+		RuntimeSlangShaderBuild build = BuildShader(shaderId);
+		{
+			std::lock_guard<std::mutex> lock(mMutex);
+			mReadyBuild = std::move(build);
+			mReadyBuild.available = true;
+		}
+		mRunning.store(false, std::memory_order_release);
+	});
+}
+
+void RuntimeSlangShaderCompiler::Stop()
+{
+	if (mThread.joinable())
+		mThread.join();
+	mRunning.store(false, std::memory_order_release);
+}
+
+bool RuntimeSlangShaderCompiler::TryConsume(RuntimeSlangShaderBuild& build)
+{
+	std::lock_guard<std::mutex> lock(mMutex);
+	if (!mReadyBuild.available)
+		return false;
+
+	build = std::move(mReadyBuild);
+	mReadyBuild = RuntimeSlangShaderBuild();
+	return true;
+}
+
+RuntimeSlangShaderBuild RuntimeSlangShaderCompiler::BuildShader(const std::string& shaderId) const
+{
+	RuntimeSlangShaderBuild build;
+	build.artifact.shaderId = shaderId;
+
+	try
+	{
+		const std::filesystem::path repoRoot = FindRepoRoot();
+		const std::filesystem::path shaderDir = repoRoot / "shaders" / shaderId;
+		const std::filesystem::path runtimeBuildDir = repoRoot / "runtime" / "generated" / "render-cadence-compositor";
+
+		ShaderPackageRegistry registry(0);
+		ShaderPackage shaderPackage;
+		std::string error;
+		if (!registry.ParseManifest(shaderDir / "shader.json", shaderPackage, error))
+		{
+			build.succeeded = false;
+			build.message = error.empty() ? "Shader manifest parse failed." : error;
+			return build;
+		}
+		const RenderCadenceCompositor::ShaderSupportResult support =
+			RenderCadenceCompositor::CheckStatelessSinglePassShaderSupport(shaderPackage);
+		if (!support.supported)
+		{
+			build.succeeded = false;
+			build.message = support.reason;
+			return build;
+		}
+
+		const ShaderPassDefinition& pass = shaderPackage.passes.front();
+
+		ShaderCompiler compiler(
+			repoRoot,
+			runtimeBuildDir / (shaderId + ".wrapper.slang"),
+			runtimeBuildDir / (shaderId + ".generated.glsl"),
+			runtimeBuildDir / (shaderId + ".patched.glsl"),
+			0);
+
+		const auto start = std::chrono::steady_clock::now();
+		if (!compiler.BuildPassFragmentShaderSource(shaderPackage, pass, build.artifact.fragmentShaderSource, error))
+		{
+			build.succeeded = false;
+			build.message = error.empty() ? "Slang compile failed." : error;
+			return build;
+		}
+
+		const auto end = std::chrono::steady_clock::now();
+		const double milliseconds = std::chrono::duration_cast<std::chrono::duration<double, std::milli>>(end - start).count();
+		build.succeeded = true;
+		build.artifact.shaderId = shaderPackage.id;
+		build.artifact.displayName = shaderPackage.displayName;
+		build.artifact.parameterDefinitions = shaderPackage.parameters;
+		build.artifact.message = shaderPackage.displayName + " Slang compile completed in " + std::to_string(milliseconds) + " ms.";
+		build.message = build.artifact.message;
+		return build;
+	}
+	catch (const std::exception& exception)
+	{
+		build.succeeded = false;
+		build.message = exception.what();
+		return build;
+	}
+}

apps/RenderCadenceCompositor/runtime/RuntimeSlangShaderCompiler.h

@@ -0,0 +1,39 @@
+#pragma once
+
+#include "RuntimeShaderArtifact.h"
+
+#include <atomic>
+#include <mutex>
+#include <string>
+#include <thread>
+
+struct RuntimeSlangShaderBuild
+{
+	bool available = false;
+	bool succeeded = false;
+	RuntimeShaderArtifact artifact;
+	std::string message;
+};
+
+class RuntimeSlangShaderCompiler
+{
+public:
+	RuntimeSlangShaderCompiler() = default;
+	RuntimeSlangShaderCompiler(const RuntimeSlangShaderCompiler&) = delete;
+	RuntimeSlangShaderCompiler& operator=(const RuntimeSlangShaderCompiler&) = delete;
+	~RuntimeSlangShaderCompiler();
+
+	void StartHappyAccidentBuild();
+	void StartShaderBuild(const std::string& shaderId);
+	void Stop();
+	bool TryConsume(RuntimeSlangShaderBuild& build);
+	bool Running() const { return mRunning.load(std::memory_order_acquire); }
+
+private:
+	RuntimeSlangShaderBuild BuildShader(const std::string& shaderId) const;
+
+	std::thread mThread;
+	std::atomic<bool> mRunning{ false };
+	std::mutex mMutex;
+	RuntimeSlangShaderBuild mReadyBuild;
+};

apps/RenderCadenceCompositor/runtime/SupportedShaderCatalog.cpp

@@ -0,0 +1,83 @@
+#include "SupportedShaderCatalog.h"
+
+#include "ShaderPackageRegistry.h"
+
+#include <map>
+#include <utility>
+
+namespace RenderCadenceCompositor
+{
+ShaderSupportResult CheckStatelessSinglePassShaderSupport(const ShaderPackage& shaderPackage)
+{
+	if (shaderPackage.passes.size() != 1)
+		return { false, "RenderCadenceCompositor currently supports only single-pass runtime shaders." };
+
+	if (shaderPackage.temporal.enabled)
+		return { false, "RenderCadenceCompositor currently supports only stateless shaders; temporal history is not enabled in this app." };
+
+	if (shaderPackage.feedback.enabled)
+		return { false, "RenderCadenceCompositor currently supports only stateless shaders; feedback storage is not enabled in this app." };
+
+	if (!shaderPackage.textureAssets.empty())
+		return { false, "RenderCadenceCompositor does not load shader texture assets yet; texture-backed shaders need a CPU-prepared asset handoff first." };
+
+	if (!shaderPackage.fontAssets.empty())
+		return { false, "RenderCadenceCompositor does not load shader font assets yet; text shaders need a CPU-prepared asset handoff first." };
+
+	for (const ShaderParameterDefinition& parameter : shaderPackage.parameters)
+	{
+		if (parameter.type == ShaderParameterType::Text)
+			return { false, "RenderCadenceCompositor currently skips text parameters because they require per-shader text texture storage." };
+	}
+
+	return { true, std::string() };
+}
+
+bool SupportedShaderCatalog::Load(const std::filesystem::path& shaderRoot, unsigned maxTemporalHistoryFrames, std::string& error)
+{
+	mShaders.clear();
+	mPackagesById.clear();
+
+	if (shaderRoot.empty())
+	{
+		error = "Shader library path is empty.";
+		return false;
+	}
+
+	ShaderPackageRegistry registry(maxTemporalHistoryFrames);
+	std::map<std::string, ShaderPackage> packagesById;
+	std::vector<std::string> packageOrder;
+	std::vector<ShaderPackageStatus> packageStatuses;
+	if (!registry.Scan(shaderRoot, packagesById, packageOrder, packageStatuses, error))
+		return false;
+
+	for (const std::string& packageId : packageOrder)
+	{
+		const auto packageIt = packagesById.find(packageId);
+		if (packageIt == packagesById.end())
+			continue;
+
+		const ShaderPackage& shaderPackage = packageIt->second;
+		const ShaderSupportResult support = CheckStatelessSinglePassShaderSupport(shaderPackage);
+		if (!support.supported)
+			continue;
+
+		SupportedShaderSummary summary;
+		summary.id = shaderPackage.id;
+		summary.name = shaderPackage.displayName.empty() ? shaderPackage.id : shaderPackage.displayName;
+		summary.description = shaderPackage.description;
+		summary.category = shaderPackage.category;
+		mShaders.push_back(std::move(summary));
+		mPackagesById[shaderPackage.id] = shaderPackage;
+	}
+
+	error.clear();
+	return true;
+}
+
+const ShaderPackage* SupportedShaderCatalog::FindPackage(const std::string& shaderId) const
+{
+	const auto packageIt = mPackagesById.find(shaderId);
+	return packageIt == mPackagesById.end() ? nullptr : &packageIt->second;
+}
+}

apps/RenderCadenceCompositor/runtime/SupportedShaderCatalog.h

@@ -0,0 +1,39 @@
+#pragma once
+
+#include "ShaderTypes.h"
+
+#include <filesystem>
+#include <map>
+#include <string>
+#include <vector>
+
+namespace RenderCadenceCompositor
+{
+struct SupportedShaderSummary
+{
+	std::string id;
+	std::string name;
+	std::string description;
+	std::string category;
+};
+
+struct ShaderSupportResult
+{
+	bool supported = false;
+	std::string reason;
+};
+
+ShaderSupportResult CheckStatelessSinglePassShaderSupport(const ShaderPackage& shaderPackage);
+
+class SupportedShaderCatalog
+{
+public:
+	bool Load(const std::filesystem::path& shaderRoot, unsigned maxTemporalHistoryFrames, std::string& error);
+	const std::vector<SupportedShaderSummary>& Shaders() const { return mShaders; }
+	const ShaderPackage* FindPackage(const std::string& shaderId) const;
+
+private:
+	std::vector<SupportedShaderSummary> mShaders;
+	std::map<std::string, ShaderPackage> mPackagesById;
+};
+}

apps/RenderCadenceCompositor/telemetry/CadenceTelemetry.h

@@ -0,0 +1,102 @@
+#pragma once
+
+#include <chrono>
+#include <cstddef>
+#include <cstdint>
+
+namespace RenderCadenceCompositor
+{
+struct CadenceTelemetrySnapshot
+{
+	double sampleSeconds = 0.0;
+	double renderFps = 0.0;
+	double scheduleFps = 0.0;
+	std::size_t freeFrames = 0;
+	std::size_t completedFrames = 0;
+	std::size_t scheduledFrames = 0;
+	uint64_t renderedTotal = 0;
+	uint64_t scheduledTotal = 0;
+	uint64_t completedPollMisses = 0;
+	uint64_t scheduleFailures = 0;
+	uint64_t completions = 0;
+	uint64_t displayedLate = 0;
+	uint64_t dropped = 0;
+	uint64_t shaderBuildsCommitted = 0;
+	uint64_t shaderBuildFailures = 0;
+	bool deckLinkBufferedAvailable = false;
+	uint64_t deckLinkBuffered = 0;
+	double deckLinkScheduleCallMilliseconds = 0.0;
+};
+
+class CadenceTelemetry
+{
+public:
+	template <typename SystemFrameExchange, typename Output, typename OutputThread>
+	CadenceTelemetrySnapshot Sample(
+		const SystemFrameExchange& exchange,
+		const Output& output,
+		const OutputThread& outputThread)
+	{
+		const auto now = Clock::now();
+		const double seconds = mHasLastSample
+			? std::chrono::duration_cast<std::chrono::duration<double>>(now - mLastSampleTime).count()
+			: 0.0;
+
+		const auto exchangeMetrics = exchange.Metrics();
+		const auto outputMetrics = output.Metrics();
+		const auto threadMetrics = outputThread.Metrics();
+
+		CadenceTelemetrySnapshot snapshot;
+		snapshot.sampleSeconds = seconds;
+		snapshot.renderedTotal = exchangeMetrics.completedFrames;
+		snapshot.scheduledTotal = exchangeMetrics.scheduledFrames;
+		snapshot.freeFrames = exchangeMetrics.freeCount;
+		snapshot.completedFrames = exchangeMetrics.completedCount;
+		snapshot.scheduledFrames = exchangeMetrics.scheduledCount;
+		snapshot.completedPollMisses = threadMetrics.completedPollMisses;
+		snapshot.scheduleFailures = outputMetrics.scheduleFailures > threadMetrics.scheduleFailures
+			? outputMetrics.scheduleFailures
+			: threadMetrics.scheduleFailures;
+		snapshot.completions = outputMetrics.completions;
+		snapshot.displayedLate = outputMetrics.displayedLate;
+		snapshot.dropped = outputMetrics.dropped;
+		snapshot.deckLinkBufferedAvailable = outputMetrics.actualBufferedFramesAvailable;
+		snapshot.deckLinkBuffered = outputMetrics.actualBufferedFrames;
+		snapshot.deckLinkScheduleCallMilliseconds = outputMetrics.scheduleCallMilliseconds;
+
+		if (mHasLastSample && seconds > 0.0)
+		{
+			snapshot.renderFps = static_cast<double>(snapshot.renderedTotal - mLastRenderedFrames) / seconds;
+			snapshot.scheduleFps = static_cast<double>(snapshot.scheduledTotal - mLastScheduledFrames) / seconds;
+		}
+
+		mLastSampleTime = now;
+		mLastRenderedFrames = snapshot.renderedTotal;
+		mLastScheduledFrames = snapshot.scheduledTotal;
+		mHasLastSample = true;
+		return snapshot;
+	}
+
+	template <typename SystemFrameExchange, typename Output, typename OutputThread, typename RenderThread>
+	CadenceTelemetrySnapshot Sample(
+		const SystemFrameExchange& exchange,
+		const Output& output,
+		const OutputThread& outputThread,
+		const RenderThread& renderThread)
+	{
+		CadenceTelemetrySnapshot snapshot = Sample(exchange, output, outputThread);
+		const auto renderMetrics = renderThread.GetMetrics();
+		snapshot.shaderBuildsCommitted = renderMetrics.shaderBuildsCommitted;
+		snapshot.shaderBuildFailures = renderMetrics.shaderBuildFailures;
+		return snapshot;
+	}
+
+private:
+	using Clock = std::chrono::steady_clock;
+
+	Clock::time_point mLastSampleTime = Clock::now();
+	uint64_t mLastRenderedFrames = 0;
+	uint64_t mLastScheduledFrames = 0;
+	bool mHasLastSample = false;
+};
+}

apps/RenderCadenceCompositor/telemetry/CadenceTelemetryJson.h

@@ -0,0 +1,45 @@
+#pragma once
+
+#include "CadenceTelemetry.h"
+#include "../json/JsonWriter.h"
+
+#include <cstdint>
+#include <string>
+
+namespace RenderCadenceCompositor
+{
+inline void WriteCadenceTelemetryJson(JsonWriter& writer, const CadenceTelemetrySnapshot& snapshot)
+{
+	writer.BeginObject();
+	writer.KeyDouble("sampleSeconds", snapshot.sampleSeconds);
+	writer.KeyDouble("renderFps", snapshot.renderFps);
+	writer.KeyDouble("scheduleFps", snapshot.scheduleFps);
+	writer.KeyUInt("free", static_cast<uint64_t>(snapshot.freeFrames));
+	writer.KeyUInt("completed", static_cast<uint64_t>(snapshot.completedFrames));
+	writer.KeyUInt("scheduled", static_cast<uint64_t>(snapshot.scheduledFrames));
+	writer.KeyUInt("renderedTotal", snapshot.renderedTotal);
+	writer.KeyUInt("scheduledTotal", snapshot.scheduledTotal);
+	writer.KeyUInt("completedPollMisses", snapshot.completedPollMisses);
+	writer.KeyUInt("scheduleFailures", snapshot.scheduleFailures);
+	writer.KeyUInt("completions", snapshot.completions);
+	writer.KeyUInt("late", snapshot.displayedLate);
+	writer.KeyUInt("dropped", snapshot.dropped);
+	writer.KeyUInt("shaderCommitted", snapshot.shaderBuildsCommitted);
+	writer.KeyUInt("shaderFailures", snapshot.shaderBuildFailures);
+	writer.KeyBool("deckLinkBufferedAvailable", snapshot.deckLinkBufferedAvailable);
+	writer.Key("deckLinkBuffered");
+	if (snapshot.deckLinkBufferedAvailable)
+		writer.UInt(snapshot.deckLinkBuffered);
+	else
+		writer.Null();
+	writer.KeyDouble("scheduleCallMs", snapshot.deckLinkScheduleCallMilliseconds);
+	writer.EndObject();
+}
+
+inline std::string CadenceTelemetryToJson(const CadenceTelemetrySnapshot& snapshot)
+{
+	JsonWriter writer;
+	WriteCadenceTelemetryJson(writer, snapshot);
+	return writer.StringValue();
+}
+}

apps/RenderCadenceCompositor/telemetry/TelemetryHealthMonitor.h

@@ -0,0 +1,116 @@
+#pragma once
+
+#include "CadenceTelemetry.h"
+#include "../logging/Logger.h"
+
+#include <atomic>
+#include <chrono>
+#include <sstream>
+#include <thread>
+
+namespace RenderCadenceCompositor
+{
+struct TelemetryHealthMonitorConfig
+{
+	std::chrono::milliseconds interval = std::chrono::seconds(1);
+	std::size_t scheduledStarvationThreshold = 0;
+};
+
+class TelemetryHealthMonitor
+{
+public:
+	explicit TelemetryHealthMonitor(TelemetryHealthMonitorConfig config = TelemetryHealthMonitorConfig()) :
+		mConfig(config)
+	{
+	}
+
+	TelemetryHealthMonitor(const TelemetryHealthMonitor&) = delete;
+	TelemetryHealthMonitor& operator=(const TelemetryHealthMonitor&) = delete;
+
+	~TelemetryHealthMonitor()
+	{
+		Stop();
+	}
+
+	template <typename SystemFrameExchange, typename Output, typename OutputThread, typename RenderThread>
+	void Start(const SystemFrameExchange& exchange, const Output& output, const OutputThread& outputThread, const RenderThread& renderThread)
+	{
+		if (mRunning)
+			return;
+		mStopping = false;
+		mThread = std::thread([this, &exchange, &output, &outputThread, &renderThread]() {
+			CadenceTelemetry telemetry;
+			CadenceTelemetrySnapshot previous;
+			bool hasPrevious = false;
+			while (!mStopping)
+			{
+				std::this_thread::sleep_for(mConfig.interval);
+				const CadenceTelemetrySnapshot snapshot = telemetry.Sample(exchange, output, outputThread, renderThread);
+				ReportHealth(snapshot, hasPrevious ? &previous : nullptr);
+				previous = snapshot;
+				hasPrevious = true;
+			}
+		});
+		mRunning = true;
+	}
+
+	void Stop()
+	{
+		mStopping = true;
+		if (mThread.joinable())
+			mThread.join();
+		mRunning = false;
+	}
+
+private:
+	void ReportHealth(const CadenceTelemetrySnapshot& snapshot, const CadenceTelemetrySnapshot* previous) const
+	{
+		if (!previous)
+			return;
+
+		const uint64_t lateDelta = snapshot.displayedLate - previous->displayedLate;
+		const uint64_t droppedDelta = snapshot.dropped - previous->dropped;
+		const uint64_t scheduleFailureDelta = snapshot.scheduleFailures - previous->scheduleFailures;
+
+		if (droppedDelta > 0 || lateDelta > 0)
+		{
+			std::ostringstream message;
+			message << "DeckLink reported frame timing issue: lateDelta=" << lateDelta
+				<< " droppedDelta=" << droppedDelta
+				<< " totalLate=" << snapshot.displayedLate
+				<< " totalDropped=" << snapshot.dropped;
+			LogWarning("telemetry", message.str());
+		}
+
+		if (scheduleFailureDelta > 0)
+		{
+			std::ostringstream message;
+			message << "DeckLink schedule failures increased: delta=" << scheduleFailureDelta
+				<< " total=" << snapshot.scheduleFailures;
+			LogWarning("telemetry", message.str());
+		}
+
+		const bool appScheduledStarved = snapshot.scheduledFrames <= mConfig.scheduledStarvationThreshold
+			&& snapshot.scheduledTotal > 0;
+		const bool deckLinkStarved = snapshot.deckLinkBufferedAvailable && snapshot.deckLinkBuffered == 0;
+		if (appScheduledStarved || deckLinkStarved)
+		{
+			std::ostringstream message;
+			message << "Output buffer starvation detected: scheduled=" << snapshot.scheduledFrames
+				<< " decklinkBuffered=";
+			if (snapshot.deckLinkBufferedAvailable)
+				message << snapshot.deckLinkBuffered;
+			else
+				message << "n/a";
+			message << " renderFps=" << snapshot.renderFps
+				<< " scheduleFps=" << snapshot.scheduleFps;
+			LogError("telemetry", message.str());
+		}
+	}
+
+	TelemetryHealthMonitorConfig mConfig;
+	std::thread mThread;
+	std::atomic<bool> mStopping{ false };
+	std::atomic<bool> mRunning{ false };
+};
+}

apps/RenderCadenceCompositor/video/DeckLinkOutput.cpp

@@ -0,0 +1,105 @@
+#include "DeckLinkOutput.h"
+
+#include "VideoIOFormat.h"
+
+namespace RenderCadenceCompositor
+{
+DeckLinkOutput::~DeckLinkOutput()
+{
+	ReleaseResources();
+}
+
+bool DeckLinkOutput::Initialize(const DeckLinkOutputConfig& config, CompletionCallback completionCallback, std::string& error)
+{
+	mConfig = config;
+	mCompletionCallback = completionCallback;
+
+	VideoFormatSelection formats;
+	if (!mSession.DiscoverDevicesAndModes(formats, error))
+		return false;
+	if (!mSession.SelectPreferredFormats(formats, config.outputAlphaRequired, error))
+		return false;
+	if (!mSession.ConfigureOutput(
+		[this](const VideoIOCompletion& completion) { HandleCompletion(completion); },
+		formats.output,
+		config.externalKeyingEnabled,
+		error))
+	{
+		return false;
+	}
+	if (!mSession.PrepareOutputSchedule())
+	{
+		error = "DeckLink output schedule preparation failed.";
+		return false;
+	}
+	return true;
+}
+
+bool DeckLinkOutput::StartScheduledPlayback(std::string& error)
+{
+	if (mSession.StartScheduledPlayback())
+		return true;
+	error = "DeckLink scheduled playback failed to start.";
+	return false;
+}
+
+bool DeckLinkOutput::ScheduleFrame(const VideoIOOutputFrame& frame)
+{
+	return mSession.ScheduleOutputFrame(frame);
+}
+
+void DeckLinkOutput::Stop()
+{
+	mSession.Stop();
+}
+
+void DeckLinkOutput::ReleaseResources()
+{
+	mSession.ReleaseResources();
+}
+
+const VideoIOState& DeckLinkOutput::State() const
+{
+	return mSession.State();
+}
+
+DeckLinkOutputMetrics DeckLinkOutput::Metrics() const
+{
+	DeckLinkOutputMetrics metrics;
+	metrics.completions = mCompletions.load();
+	metrics.displayedLate = mDisplayedLate.load();
+	metrics.dropped = mDropped.load();
+	metrics.flushed = mFlushed.load();
+
+	const VideoIOState& state = mSession.State();
+	metrics.scheduleFailures = state.deckLinkScheduleFailureCount;
+	metrics.actualBufferedFramesAvailable = state.actualDeckLinkBufferedFramesAvailable;
+	metrics.actualBufferedFrames = state.actualDeckLinkBufferedFrames;
+	metrics.scheduleCallMilliseconds = state.deckLinkScheduleCallMilliseconds;
+	return metrics;
+}
+
+void DeckLinkOutput::HandleCompletion(const VideoIOCompletion& completion)
+{
+	++mCompletions;
+	switch (completion.result)
+	{
+	case VideoIOCompletionResult::DisplayedLate:
+		++mDisplayedLate;
+		break;
+	case VideoIOCompletionResult::Dropped:
+		++mDropped;
+		break;
+	case VideoIOCompletionResult::Flushed:
+		++mFlushed;
+		break;
+	case VideoIOCompletionResult::Completed:
+	case VideoIOCompletionResult::Unknown:
+	default:
+		break;
+	}
+
+	if (mCompletionCallback)
+		mCompletionCallback(completion);
+}
+}

apps/RenderCadenceCompositor/video/DeckLinkOutput.h

@@ -0,0 +1,61 @@
+#pragma once
+
+#include "DeckLinkSession.h"
+#include "VideoIOTypes.h"
+
+#include <atomic>
+#include <cstdint>
+#include <functional>
+#include <string>
+
+namespace RenderCadenceCompositor
+{
+struct DeckLinkOutputConfig
+{
+	bool externalKeyingEnabled = false;
+	bool outputAlphaRequired = false;
+};
+
+struct DeckLinkOutputMetrics
+{
+	uint64_t completions = 0;
+	uint64_t displayedLate = 0;
+	uint64_t dropped = 0;
+	uint64_t flushed = 0;
+	uint64_t scheduleFailures = 0;
+	bool actualBufferedFramesAvailable = false;
+	uint64_t actualBufferedFrames = 0;
+	double scheduleCallMilliseconds = 0.0;
+};
+
+class DeckLinkOutput
+{
+public:
+	using CompletionCallback = std::function<void(const VideoIOCompletion&)>;
+
+	DeckLinkOutput() = default;
+	DeckLinkOutput(const DeckLinkOutput&) = delete;
+	DeckLinkOutput& operator=(const DeckLinkOutput&) = delete;
+	~DeckLinkOutput();
+
+	bool Initialize(const DeckLinkOutputConfig& config, CompletionCallback completionCallback, std::string& error);
+	bool StartScheduledPlayback(std::string& error);
+	bool ScheduleFrame(const VideoIOOutputFrame& frame);
+	void Stop();
+	void ReleaseResources();
+
+	const VideoIOState& State() const;
+	DeckLinkOutputMetrics Metrics() const;
+
+private:
+	void HandleCompletion(const VideoIOCompletion& completion);
+
+	DeckLinkSession mSession;
+	DeckLinkOutputConfig mConfig;
+	CompletionCallback mCompletionCallback;
+	std::atomic<uint64_t> mCompletions{ 0 };
+	std::atomic<uint64_t> mDisplayedLate{ 0 };
+	std::atomic<uint64_t> mDropped{ 0 };
+	std::atomic<uint64_t> mFlushed{ 0 };
+};
+}

apps/RenderCadenceCompositor/video/DeckLinkOutputThread.h

@@ -0,0 +1,124 @@
+#pragma once
+
+#include "../frames/SystemFrameTypes.h"
+#include "DeckLinkOutput.h"
+#include "VideoIOTypes.h"
+
+#include <atomic>
+#include <chrono>
+#include <cstddef>
+#include <cstdint>
+#include <thread>
+
+namespace RenderCadenceCompositor
+{
+struct DeckLinkOutputThreadConfig
+{
+	std::size_t targetBufferedFrames = 4;
+	std::chrono::milliseconds idleSleep = std::chrono::milliseconds(1);
+};
+
+struct DeckLinkOutputThreadMetrics
+{
+	uint64_t scheduledFrames = 0;
+	uint64_t completedPollMisses = 0;
+	uint64_t scheduleFailures = 0;
+};
+
+template <typename SystemFrameExchange>
+class DeckLinkOutputThread
+{
+public:
+	DeckLinkOutputThread(DeckLinkOutput& output, SystemFrameExchange& exchange, DeckLinkOutputThreadConfig config = DeckLinkOutputThreadConfig()) :
+		mOutput(output),
+		mExchange(exchange),
+		mConfig(config)
+	{
+	}
+
+	DeckLinkOutputThread(const DeckLinkOutputThread&) = delete;
+	DeckLinkOutputThread& operator=(const DeckLinkOutputThread&) = delete;
+
+	~DeckLinkOutputThread()
+	{
+		Stop();
+	}
+
+	bool Start()
+	{
+		if (mRunning)
+			return true;
+		mStopping = false;
+		mThread = std::thread([this]() { ThreadMain(); });
+		mRunning = true;
+		return true;
+	}
+
+	void Stop()
+	{
+		mStopping = true;
+		if (mThread.joinable())
+			mThread.join();
+		mRunning = false;
+	}
+
+	DeckLinkOutputThreadMetrics Metrics() const
+	{
+		DeckLinkOutputThreadMetrics metrics;
+		metrics.scheduledFrames = mScheduledFrames.load();
+		metrics.completedPollMisses = mCompletedPollMisses.load();
+		metrics.scheduleFailures = mScheduleFailures.load();
+		return metrics;
+	}
+
+private:
+	void ThreadMain()
+	{
+		while (!mStopping)
+		{
+			const auto exchangeMetrics = mExchange.Metrics();
+			if (exchangeMetrics.scheduledCount >= mConfig.targetBufferedFrames)
+			{
+				std::this_thread::sleep_for(mConfig.idleSleep);
+				continue;
+			}
+
+			SystemFrame frame;
+			if (!mExchange.ConsumeCompletedForSchedule(frame))
+			{
+				++mCompletedPollMisses;
+				std::this_thread::sleep_for(mConfig.idleSleep);
+				continue;
+			}
+
+			VideoIOOutputFrame outputFrame;
+			outputFrame.bytes = frame.bytes;
+			outputFrame.nativeBuffer = frame.bytes;
+			outputFrame.rowBytes = frame.rowBytes;
+			outputFrame.width = frame.width;
+			outputFrame.height = frame.height;
+			outputFrame.pixelFormat = frame.pixelFormat;
+
+			if (!mOutput.ScheduleFrame(outputFrame))
+			{
+				++mScheduleFailures;
+				mExchange.ReleaseScheduledByBytes(frame.bytes);
+				std::this_thread::sleep_for(mConfig.idleSleep);
+				continue;
+			}
+
+			++mScheduledFrames;
+		}
+	}
+
+	DeckLinkOutput& mOutput;
+	SystemFrameExchange& mExchange;
+	DeckLinkOutputThreadConfig mConfig;
+	std::thread mThread;
+	std::atomic<bool> mStopping{ false };
+	std::atomic<bool> mRunning{ false };
+	std::atomic<uint64_t> mScheduledFrames{ 0 };
+	std::atomic<uint64_t> mCompletedPollMisses{ 0 };
+	std::atomic<uint64_t> mScheduleFailures{ 0 };
+};
+}

docs/CURRENT_SYSTEM_ARCHITECTURE.md

@@ -4,6 +4,14 @@ This document describes how the application currently works.
 
 It replaces the phase-by-phase design trail as the best entry point for understanding the repo. The older phase documents remain useful history, but they mix implementation notes, experiments, and target designs. This document is organized by current runtime behavior and subsystem ownership instead.
 
+The active plan for tightening render-thread ownership is:
+
+- [Render Thread Ownership Plan](RENDER_THREAD_OWNERSHIP_PLAN.md)
+
+The plan for building a fresh modular app around the proven probe architecture is:
+
+- [New Render Cadence App Plan](NEW_RENDER_CADENCE_APP_PLAN.md)
+
 ## Application Shape
 
 The app is a live OpenGL compositor with DeckLink input/output, runtime control services, persistent layer-stack state, live state overlays, health telemetry, and a small internal event model.

docs/NEW_RENDER_CADENCE_APP_PLAN.md

@@ -0,0 +1,578 @@
+# New Render Cadence App Plan
+
+This plan describes a new application folder that rebuilds the output path from the proven `DeckLinkRenderCadenceProbe` architecture, but as a maintainable app foundation rather than a monolithic probe file.
+
+The first goal is not to port the current compositor feature set. The first goal is to reproduce the probe's smooth 59.94/60 fps DeckLink output with clean module boundaries, tests where possible, and a structure that can later accept the shader/runtime/control systems without compromising timing.
+
+## Working Name
+
+Suggested folder:
+
+```text
+apps/RenderCadenceCompositor
+```
+
+Suggested executable:
+
+```text
+RenderCadenceCompositor
+```
+
+The existing app remains intact:
+
+```text
+apps/LoopThroughWithOpenGLCompositing
+```
+
+The probe remains the control sample:
+
+```text
+apps/DeckLinkRenderCadenceProbe
+```
+
+## Design Principle
+
+The app is built around one spine:
+
+```text
+Render cadence thread
+  -> owns GL context
+  -> renders at selected frame cadence
+  -> performs async BGRA8 readback
+  -> publishes completed system-memory frames
+
+System frame exchange
+  -> owns Free / Rendering / Completed / Scheduled slots
+  -> latest-N semantics for completed unscheduled frames
+  -> protects scheduled frames until DeckLink completion
+
+DeckLink output thread
+  -> consumes completed frames
+  -> schedules to target buffer depth
+  -> releases scheduled frames on completion
+  -> never renders
+```
+
+Everything else must fit around that spine.
+
+## Non-Negotiable Rules
+
+- The render thread owns its GL context from initialization to shutdown.
+- The render thread is driven by selected render cadence, not DeckLink demand.
+- DeckLink scheduling never calls render code.
+- Completion callbacks never render.
+- No synchronous render request exists in the output path.
+- Preview, screenshot, input upload, shader rebuild, and runtime control cannot run ahead of a due output frame.
+- Completed unscheduled frames are latest-N and disposable.
+- Scheduled frames are protected until DeckLink completion.
+- Startup warms up real rendered frames before scheduled playback starts.
+
+## Borrow From The Probe
+
+Keep these behaviors from `DeckLinkRenderCadenceProbe`:
+
+- hidden OpenGL context owned by the render thread
+- simple render loop with `nextRenderTime`
+- BGRA8 render target
+- PBO ring readback
+- non-blocking fence polling with zero timeout
+- system-memory slots with `Free`, `Rendering`, `Completed`, `Scheduled`
+- drop oldest completed unscheduled frame if render needs space
+- DeckLink playout thread only schedules completed frames
+- warmup completed frames before `StartScheduledPlayback()`
+- one-line-per-second timing telemetry
+
+## Do Not Borrow Directly
+
+The probe is deliberately compact. Do not carry over these probe limitations into the new app:
+
+- one huge `.cpp` file
+- hard-coded output mode as permanent behavior
+- render pattern, frame store, PBO logic, DeckLink playout, COM setup, and telemetry mixed together
+- no reusable interfaces
+- no unit-testable non-GL core
+
+## Proposed Folder Structure
+
+```text
+apps/RenderCadenceCompositor/
+  README.md
+  RenderCadenceCompositor.cpp
+
+  app/
+    RenderCadenceApp.cpp
+    RenderCadenceApp.h
+    AppConfig.cpp
+    AppConfig.h
+    AppConfigProvider.cpp
+    AppConfigProvider.h
+
+  control/
+    HttpControlServer.cpp
+    HttpControlServer.h
+    RuntimeStateJson.h
+
+  platform/
+    ComInit.cpp
+    ComInit.h
+    HiddenGlWindow.cpp
+    HiddenGlWindow.h
+    Win32Console.cpp
+    Win32Console.h
+
+  render/
+    RenderThread.cpp
+    RenderThread.h
+    RenderCadenceClock.cpp
+    RenderCadenceClock.h
+    SimpleMotionRenderer.cpp
+    SimpleMotionRenderer.h
+    Bgra8ReadbackPipeline.cpp
+    Bgra8ReadbackPipeline.h
+    PboReadbackRing.cpp
+    PboReadbackRing.h
+
+  frames/
+    SystemFrameExchange.cpp
+    SystemFrameExchange.h
+    SystemFrameTypes.h
+
+  video/
+    DeckLinkOutput.cpp
+    DeckLinkOutput.h
+    DeckLinkOutputThread.cpp
+    DeckLinkOutputThread.h
+
+  telemetry/
+    CadenceTelemetry.cpp
+    CadenceTelemetry.h
+    CadenceTelemetryJson.h
+    TelemetryHealthMonitor.h
+
+  logging/
+    Logger.cpp
+    Logger.h
+
+  json/
+    JsonWriter.cpp
+    JsonWriter.h
+```
+
+The new app can reuse selected existing source files from the current app at first:
+
+- `videoio/decklink/DeckLinkSession.*`
+- `videoio/decklink/DeckLinkDisplayMode.*`
+- `videoio/decklink/DeckLinkVideoIOFormat.*`
+- `videoio/decklink/DeckLinkFrameTransfer.*`
+- `videoio/VideoIOFormat.*`
+- `videoio/VideoIOTypes.h`
+- `videoio/VideoPlayoutScheduler.*`
+- `gl/renderer/GLExtensions.*`
+
+Longer term, shared code should move into common libraries, but the first version can link these files directly to avoid a big build-system refactor.
+
+## Module Responsibilities
+
+### `RenderCadenceApp`
+
+Owns top-level startup/shutdown sequencing.
+
+Responsibilities:
+
+- initialize COM
+- discover/select DeckLink output
+- create frame exchange
+- start render thread
+- wait for completed-frame warmup
+- start DeckLink output thread
+- wait for scheduled buffer warmup
+- start DeckLink scheduled playback
+- start telemetry printer
+- stop in reverse order
+
+It should not contain OpenGL drawing code, frame slot policy, or DeckLink scheduling loops.
+
+### `AppConfig`
+
+Owns runtime settings for the initial app.
+
+Initial settings:
+
+- output mode preference
+- output width/height validation
+- frame buffer capacity
+- PBO depth
+- warmup completed-frame count
+- target DeckLink scheduled depth
+- telemetry interval
+
+Initial values should match the successful probe:
+
+```text
+systemFrameSlots = 12
+pboDepth = 6
+warmupFrames = 4
+targetDeckLinkBufferedFrames = 4
+pixelFormat = BGRA8
+```
+
+### `HiddenGlWindow`
+
+Owns hidden Win32 window, device context, and OpenGL context creation.
+
+Responsibilities:
+
+- create hidden window with `CS_OWNDC`
+- choose/set pixel format
+- create `HGLRC`
+- expose `MakeCurrent()` and `ClearCurrent()`
+- destroy context/window safely
+
+Only `RenderThread` should call `MakeCurrent()` after startup.
+
+### `RenderThread`
+
+Owns the render loop and GL context for its full lifetime.
+
+Responsibilities:
+
+- create/bind hidden GL context
+- resolve GL extensions
+- initialize renderer/readback pipeline
+- run cadence loop
+- render one frame when due
+- queue PBO readback
+- consume completed PBOs into `SystemFrameExchange`
+- record telemetry
+- destroy GL resources on the render thread
+
+It must not:
+
+- wait for DeckLink
+- schedule DeckLink frames
+- block on a system frame slot if only completed unscheduled frames can be dropped
+- accept arbitrary GL tasks ahead of output frames
+
+### `RenderCadenceClock`
+
+Small, testable cadence helper.
+
+Responsibilities:
+
+- track target frame duration
+- return whether a render is due
+- compute sleep duration
+- detect overrun/skipped ticks
+- never speed up to fill buffers
+
+This should be unit tested without GL.
+
+### `SimpleMotionRenderer`
+
+First renderer only.
+
+Responsibilities:
+
+- render obvious smooth motion and color changes
+- produce BGRA8-compatible framebuffer content
+- make dropped/repeated frames visually obvious
+
+This intentionally avoids shader-package/runtime complexity.
+
+### `Bgra8ReadbackPipeline`
+
+Owns output framebuffer and BGRA8 readback orchestration.
+
+Responsibilities:
+
+- configure render target dimensions
+- render into an RGBA8/BGRA-compatible texture
+- coordinate `PboReadbackRing`
+- publish completed frames into `SystemFrameExchange`
+
+### `PboReadbackRing`
+
+Owns PBO/fence state.
+
+Responsibilities:
+
+- queue readback into the next free PBO slot
+- poll completed fences with zero timeout
+- map/copy completed PBOs into provided system-memory slots
+- count PBO misses
+- clean up fences/PBOs on render thread
+
+This is GL-backed, but the state model should be small and easy to reason about.
+
+### `SystemFrameExchange`
+
+The central handoff between render and video.
+
+Responsibilities:
+
+- own system-memory frame buffers
+- track slot states: `Free`, `Rendering`, `Completed`, `Scheduled`
+- provide `AcquireForRender()`
+- provide `PublishCompleted()`
+- provide `ConsumeCompletedForSchedule()`
+- provide `ReleaseScheduledByBytes()`
+- drop oldest completed unscheduled frame when render needs a slot
+- expose metrics
+
+This should be unit tested heavily.
+
+### `DeckLinkOutput`
+
+Thin wrapper around `DeckLinkSession` for output-only use.
+
+Responsibilities:
+
+- discover/select output mode
+- configure output callback
+- prepare output schedule
+- schedule app-owned system-memory frames
+- start scheduled playback
+- stop/release resources
+- expose actual DeckLink buffered count
+
+No input support in the first version.
+
+### `DeckLinkOutputThread`
+
+Owns playout scheduling loop.
+
+Responsibilities:
+
+- keep scheduled depth near target
+- consume completed frames from `SystemFrameExchange`
+- schedule them through `DeckLinkOutput`
+- release frame if scheduling fails
+- sleep briefly when scheduled buffer is full or no completed frame exists
+
+It must not render.
+
+### `CadenceTelemetry`
+
+Owns counters, not policy.
+
+Initial counters:
+
+- rendered frames
+- completed readback frames
+- scheduled frames
+- completion count
+- completed-frame drops
+- acquire misses
+- schedule underruns
+- PBO queue misses
+- DeckLink late count
+- DeckLink dropped count
+- free/rendering/completed/scheduled slot counts
+- actual DeckLink buffered frames
+
+### `TelemetryHealthMonitor`
+
+Samples cadence telemetry once per interval and logs only health events.
+
+Normal telemetry is available through the HTTP state endpoint. The console should not receive a healthy once-per-second cadence line.
+
+Health events:
+
+- warning when DeckLink late/dropped-frame counters increase
+- warning when schedule failures increase
+- error when app/DeckLink output buffering is starved
+
+## Startup Sequence
+
+Target first-version startup:
+
+```text
+main
+  -> load AppConfig through AppConfigProvider
+  -> initialize COM
+  -> create SystemFrameExchange
+  -> start RenderThread
+  -> wait for completed frame warmup
+  -> optionally discover/select/configure DeckLink output
+  -> if DeckLink is available:
+       -> start DeckLinkOutputThread
+       -> wait for scheduled depth warmup
+       -> DeckLinkOutput start scheduled playback
+  -> if DeckLink is unavailable:
+       -> continue without video output
+  -> start TelemetryHealthMonitor
+  -> start HttpControlServer
+  -> wait for Enter
+```
+
+Shutdown:
+
+```text
+stop HttpControlServer
+stop TelemetryHealthMonitor
+stop DeckLinkOutputThread
+DeckLinkOutput stop playback
+stop RenderThread
+DeckLinkOutput release resources
+release COM
+```
+
+## First Milestone: Modular Probe Equivalent
+
+This is the only goal for the initial implementation.
+
+Feature set:
+
+- console app
+- output-only DeckLink
+- no input
+- hidden GL context
+- simple motion renderer
+- BGRA8 only
+- PBO async readback
+- latest-N system-memory frame exchange
+- warmup before playback
+- one-line telemetry
+
+Acceptance:
+
+- visible DeckLink output is smooth
+- `renderFps` near selected cadence
+- `scheduleFps` near selected cadence
+- scheduled count/decklink buffered count stable around 4
+- no continuous late/drop count
+- no continuous PBO misses
+- behavior matches or exceeds `DeckLinkRenderCadenceProbe`
+
+## Second Milestone: Testable Core
+
+Before porting compositor features, add tests for non-GL/non-DeckLink pieces.
+
+Test targets:
+
+- `SystemFrameExchangeTests`
+- `RenderCadenceClockTests`
+- `CadenceTelemetryTests`
+
+Important cases:
+
+- slot lifecycle transitions
+- scheduled slots are protected
+- completed unscheduled frames can be dropped
+- stale handles/generations are rejected
+- cadence does not speed up to refill buffers
+- cadence records overrun/skipped ticks
+
+## Third Milestone: Replace Simple Renderer With Render Interface
+
+Add an interface around frame rendering:
+
+```text
+IRenderScene
+  -> InitializeGl()
+  -> RenderFrame(frameIndex, time)
+  -> ShutdownGl()
+```
+
+The first implementation remains `SimpleMotionRenderer`.
+
+This creates the insertion point for shader-package rendering later without changing timing/scheduling.
+
+## Fourth Milestone: Begin Porting Current App Features
+
+Port only after the modular probe equivalent is stable.
+
+Suggested order:
+
+1. shader package compile/load
+2. render pass/layer stack drawing
+3. runtime snapshot input to renderer
+4. live state overlays
+5. control services
+6. persistence/runtime store
+7. preview from system-memory frames
+8. screenshot from system-memory frames
+9. input capture via CPU latest-frame mailbox
+
+Each port must preserve the rule that the render thread cadence is primary.
+
+## What Not To Port Early
+
+Do not port these until the output spine is proven:
+
+- DeckLink input
+- preview GL presentation
+- screenshot GL readback
+- HTTP/OSC control services
+- shader hot reload
+- persistence
+- runtime state JSON/open API
+- complex telemetry/event dispatch
+
+These are useful, but they are exactly the kinds of features that can accidentally reintroduce timing coupling.
+
+## Build Plan
+
+Initial CMake can follow the probe pattern:
+
+```cmake
+set(RENDER_CADENCE_APP_DIR "${CMAKE_CURRENT_SOURCE_DIR}/apps/RenderCadenceCompositor")
+
+add_executable(RenderCadenceCompositor
+  # selected shared DeckLink/video/gl support files
+  # new modular app files
+)
+```
+
+Later, shared source should be split into libraries:
+
+```text
+video_shader_decklink
+video_shader_videoio
+video_shader_gl_support
+render_cadence_core
+```
+
+Avoid doing that library split before the first modular app works.
+
+## VS Code Launch
+
+Add a separate launch profile:
+
+```text
+Debug RenderCadenceCompositor
+```
+
+Run it as a console app so telemetry remains visible.
+
+## Documentation
+
+Add:
+
+```text
+apps/RenderCadenceCompositor/README.md
+```
+
+The README should record:
+
+- intended architecture
+- build/run instructions
+- expected telemetry
+- test result notes
+- differences from the old app
+- differences from the probe
+
+## Success Criteria Before Porting More Features
+
+Do not start feature porting until the new app can run with:
+
+- stable smooth DeckLink output
+- stable target scheduled depth
+- stable actual DeckLink buffered count
+- no regular visible freezes
+- no steady PBO misses
+- no steadily increasing late/dropped completions
+- focus/minimize changes do not affect output cadence
+- clean shutdown without hangs
+
+This gives us a clean foundation. Once this is true, every feature added later has to prove it does not damage the spine.

docs/RENDER_CADENCE_GOLDEN_RULES.md

@@ -0,0 +1,148 @@
+# Render Cadence Golden Rules
+
+These are the non-negotiable rules for the new render-cadence architecture.
+
+They exist because the old app drifted into a place where DeckLink timing, render work, shader build work, state coordination, readback, and recovery behavior all influenced each other. The new app should stay boring, explicit, and easy to reason about.
+
+## 1. The Render Thread Owns Its GL Context
+
+Only the render thread may bind and use its primary OpenGL context.
+
+Allowed on the render thread:
+
+- GL resource creation and destruction for resources it owns
+- GL shader/program swap from an already-prepared GL program
+- drawing the next frame
+- async readback queueing and completion polling
+- publishing completed system-memory frames
+
+Not allowed on the render thread:
+
+- Slang compiler invocation
+- manifest scanning/parsing
+- filesystem discovery
+- image/font/LUT decoding
+- persistence
+- network/API/OSC handling
+- DeckLink scheduling
+- blocking console logging
+- config file discovery or parsing
+
+If GL preparation happens off-thread, use an explicit shared-context GL prepare thread. Do not smuggle non-render work back into the cadence loop.
+
+## 2. Render Cadence Does Not Chase Buffers
+
+The render thread runs at the selected render cadence.
+
+It must not speed up to fill a DeckLink/system-memory buffer, and it must not slow down because a consumer is late. If the GPU is genuinely overloaded, record that as render overrun telemetry.
+
+Buffers absorb timing differences. They do not control render cadence.
+
+## 3. Video I/O Never Renders
+
+DeckLink output consumes already-rendered system-memory frames.
+
+The output/scheduling side may:
+
+- schedule completed frames
+- release frames after DeckLink completion
+- report late/dropped/schedule telemetry
+- record app-side poll misses
+
+It must not:
+
+- render fallback frames
+- invoke GL
+- compile shaders
+- block the render cadence waiting for DeckLink
+
+If no completed frame is available, record the miss and keep the ownership boundary intact.
+
+## 4. Runtime Build Work Produces Artifacts
+
+Runtime shader work is split into two phases:
+
+1. CPU/build phase outside the render thread
+2. shared-context GL preparation outside the render thread where practical
+3. GL program swap on the render thread
+
+The CPU/build phase may parse manifests, invoke Slang, validate package shape, and prepare CPU-side data.
+
+The render thread receives completed render-layer artifacts, asks the shared-context prepare worker to compile/link changed GL programs, and only swaps in prepared programs at a frame boundary. A failed artifact or failed GL preparation must not disturb the current renderer.
+
+The display/render layer model is app-owned. It may track requested shaders, build state, display metadata, and render-ready artifacts, but it must not perform GL work or drive render cadence directly.
+
+## 5. No Hidden Blocking In The Cadence Path
+
+The render loop must not do work with unbounded or OS-dependent latency.
+
+Examples to avoid:
+
+- file reads
+- directory scans
+- image decoding
+- process launches
+- waits on worker threads
+- blocking locks around slow code
+- synchronous GPU readback waits
+- console I/O
+
+Short mutex use for exchanging small already-prepared objects is acceptable. Holding a lock while doing heavy work is not.
+
+## 6. System Memory Frames Are A Handoff, Not A Render Driver
+
+The system-memory frame exchange stores the latest rendered frames and protects frames scheduled to DeckLink.
+
+It may drop old completed, unscheduled frames when the render thread needs a free slot. It must never force the render thread to wait for the output side to consume a frame.
+
+## 7. Startup Uses Warmup, Not Burst Rendering
+
+DeckLink playback starts only after the render thread has produced enough real frames for preroll.
+
+Warmup should happen at normal render cadence. Do not temporarily accelerate the renderer to fill buffers.
+
+## 8. Telemetry Must Name Ownership Clearly
+
+Counters should say which subsystem had the event.
+
+Good examples:
+
+- `renderFps`
+- `scheduleFps`
+- `completedPollMisses`
+- `scheduleFailures`
+- `decklinkBuffered`
+- `shaderCommitted`
+- `shaderFailures`
+
+Avoid ambiguous names like `underrun` unless it is clear whether it means app-ready underrun, DeckLink buffered-frame underrun, render overrun, or schedule failure.
+
+## 9. Keep Files Small And Role-Based
+
+A file should have one clear reason to change.
+
+Preferred boundaries:
+
+- app orchestration
+- render cadence/thread ownership
+- GL rendering
+- runtime artifact build/bridge
+- app-owned display/render layer model
+- parameter packing
+- system-memory frame exchange
+- DeckLink output scheduling
+- telemetry
+- local control/API edge
+- config loading
+- JSON presentation/serialization
+- logging
+
+If a file starts coordinating multiple subsystems and doing detailed work for each of them, split it before it becomes the new old app.
+
+## 10. Prefer Explicit Unsupported States
+
+If a feature needs storage, timing behavior, or ownership we have not designed yet, reject it clearly.
+
+For example, in the current new app it is better to reject texture/LUT/text/temporal/feedback shaders than to quietly load files or allocate history state on the render thread.
+
+Unsupported is healthy when it protects the architecture.

docs/RENDER_THREAD_OWNERSHIP_PLAN.md

@@ -0,0 +1,448 @@
+# Render Thread Ownership Plan
+
+This plan describes how to make the main compositor behave like the successful `DeckLinkRenderCadenceProbe`: one render cadence owner, one GL context owner, no unrelated work able to interrupt output frame production.
+
+The goal is not just "all GL calls happen on one thread". The current app mostly does that during runtime already. The real goal is:
+
+- the output render thread owns its GL context for its whole lifetime
+- output cadence is driven by the render thread, not by DeckLink completion timing
+- non-output GL work cannot sit ahead of output frames
+- callers cannot block the render thread while waiting for synchronous answers
+- DeckLink scheduling consumes completed system-memory frames and never causes rendering
+
+## Current Risk Points
+
+The current main app still has several ways to interrupt output cadence.
+
+### Shared GL Executor
+
+`RenderEngine` owns the GL context during runtime, but it acts as a general task executor.
+
+The same queue/path can run:
+
+- output frame render
+- input upload
+- preview present
+- screenshot capture
+- render resets
+- shader/program commits
+- resource resize
+- state clearing
+
+That means output frames are not guaranteed to be the next GL work item at the selected frame time.
+
+### Synchronous Output Render Request
+
+`VideoBackend` drives output production from its output producer thread, then calls:
+
+```text
+VideoBackend
+  -> OpenGLVideoIOBridge::RenderScheduledFrame
+  -> RenderEngine::RequestOutputFrame
+  -> TryInvokeOnRenderThread
+```
+
+That makes output production a request/response interaction. The producer waits for the render thread, and the render thread is still shared with other work.
+
+### Input Upload Shares Output Context
+
+DeckLink input capture currently flows into:
+
+```text
+VideoBackend::HandleInputFrame
+  -> OpenGLVideoIOBridge::UploadInputFrame
+  -> RenderEngine::QueueInputFrame
+  -> render thread upload
+```
+
+Even with coalescing, input upload can consume render-thread time and GPU bandwidth directly before output rendering.
+
+### Preview And Screenshot Share Output Context
+
+Preview and screenshot are lower-priority features, but today they still execute on the render thread.
+
+Preview is best-effort at the caller side, but once queued it can still occupy the same context. Screenshot capture can be more expensive because it performs readback and CPU-side image preparation.
+
+### Startup Context Ownership Is Transitional
+
+The Win32 startup path creates and binds the GL context before `RenderEngine::StartRenderThread()`.
+
+That is acceptable as a transitional state, but the final model should make context ownership explicit:
+
+- bootstrap thread creates the window/context
+- bootstrap thread releases it
+- render thread binds it
+- only render thread initializes GL resources
+- only render thread destroys GL resources
+
+### Render Callback Re-enters App State
+
+`OpenGLRenderPipeline::RenderFrame()` calls a callback into `OpenGLComposite::renderEffect()`.
+
+That callback builds `RenderFrameInput`, resolves frame state, drains runtime live state, and then calls back into `RenderEngine` to draw the prepared frame.
+
+This works, but it means the output render path still reaches up into app/runtime code at frame time.
+
+## Target Runtime Shape
+
+The main app should match this ownership model:
+
+```text
+runtime/control threads
+  -> publish snapshots, live overlays, reset requests, shader-build results
+  -> never call GL
+
+render cadence thread
+  -> sole owner of output GL context
+  -> wakes at selected render cadence
+  -> samples latest render input/state
+  -> renders one frame
+  -> queues async readback/copies completed readback into system-memory slot
+  -> publishes completed frame to latest-N output buffer
+
+video output thread
+  -> consumes completed system-memory frames
+  -> schedules DeckLink frames to target buffer depth
+  -> processes completion results
+  -> never calls GL
+
+optional input upload path
+  -> writes latest input frame into CPU-side latest-frame buffer
+  -> render thread imports/uploads at a controlled point in its frame
+
+preview/screenshot path
+  -> consumes already-rendered output/system-memory frame when possible
+  -> never interrupts output render cadence
+```
+
+## Non-Negotiable Rules
+
+- The render thread never waits for DeckLink.
+- DeckLink callbacks never render.
+- Runtime/control threads never directly execute GL.
+- Preview and screenshot never execute ahead of output frames.
+- Input upload is never a separate urgent GL task ahead of output render.
+- Shader/resource commits are applied only at a frame boundary.
+- Telemetry on the hot path must be lock-light or try-lock only.
+- The render thread cadence does not speed up to refill buffers.
+- If output work overruns, the render thread records the overrun and resumes the selected cadence policy.
+
+## Implementation Plan
+
+### 1. Add Thread/Context Ownership Guards
+
+Add explicit render-thread ownership checks around all GL entry points.
+
+Deliverables:
+
+- `RenderEngine` exposes `IsOnRenderThread()` for assertions/tests.
+- GL-facing classes get debug-only owner checks where practical.
+- wrong-thread GL access becomes a counted telemetry warning, not just `OutputDebugStringA`.
+- tests cover that public request methods do not execute GL directly.
+
+Acceptance:
+
+- every `RenderEngine` public method is classified as either request-only, lifecycle-only, or render-thread-only.
+- render-thread-only methods are private or guarded.
+- no normal runtime caller can accidentally invoke GL work inline.
+
+### 2. Move GL Initialization Fully Onto The Render Thread
+
+Start the render thread before compiling shaders and initializing GL resources.
+
+Current startup does:
+
+```text
+InitOpenGLState()
+  -> CompileDecodeShader
+  -> CompileOutputPackShader
+  -> InitializeResources
+  -> CompileLayerPrograms
+StartRenderThread()
+```
+
+Move toward:
+
+```text
+create context on Win32 thread
+release context on Win32 thread
+StartRenderThread()
+render thread binds context
+render thread initializes extensions, shaders, resources
+```
+
+Deliverables:
+
+- a single `RenderEngine::StartAndInitialize(RenderInitializationConfig)` path.
+- GL extension resolution happens on the render thread.
+- shader/resource initialization is a render-thread startup phase.
+- `RenderEngine` destructor only destroys resources on the render thread.
+
+Acceptance:
+
+- after `StartRenderThread()`, no non-render thread binds or uses the app GL context.
+- shutdown order is deterministic: stop video output, stop render cadence, destroy GL resources, release context.
+
+### 3. Replace Synchronous Output Render Requests With Render-Owned Cadence
+
+Move output cadence out of `VideoBackend` and into the render system.
+
+Current:
+
+```text
+VideoBackend output producer
+  -> cadence tick
+  -> acquire output slot
+  -> synchronous render-thread request
+```
+
+Target:
+
+```text
+RenderEngine output cadence loop
+  -> cadence tick
+  -> acquire/free output slot through a non-blocking frame-sink interface
+  -> render frame
+  -> publish completed frame
+```
+
+Deliverables:
+
+- introduce `RenderedFrameSink` or similar interface owned by video output.
+- render thread pulls/claims a free system-memory slot without waiting.
+- if no free slot exists, render thread drops/recycles the oldest unscheduled completed frame or records backpressure without blocking.
+- remove `RenderEngine::RequestOutputFrame()` from the steady-state output path.
+
+Acceptance:
+
+- output rendering continues even if DeckLink completion is delayed.
+- no `std::future` wait exists in the output cadence path.
+- `VideoBackend` no longer owns the producer render loop; it owns scheduling/completion only.
+
+### 4. Make The Render Thread A Frame Loop, Not A Task Queue
+
+Keep a command mailbox, but process it only at safe frame-boundary points.
+
+Frame loop:
+
+```text
+while running:
+  wait until next render timestamp
+  apply bounded frame-boundary commands
+  sample latest frame input/state
+  upload latest input frame if enabled and budget allows
+  render output frame
+  queue/consume readback
+  publish completed frame
+  record timings
+```
+
+Command classes:
+
+- frame-boundary commands: reset temporal history, reset shader feedback, commit prepared shader programs
+- background/low-priority commands: preview, screenshot, diagnostic readback
+- non-GL commands: state publication, telemetry, persistence
+
+Deliverables:
+
+- replace FIFO render task queue with a priority/mailbox model.
+- output cadence is the loop's main clock.
+- commands have budget classes and max work per frame.
+- long commands are deferred rather than blocking the current output tick.
+
+Acceptance:
+
+- preview/screenshot cannot run immediately before a due output frame.
+- reset/shader work is applied between frames and measured.
+- output render starts within a small jitter window when the GPU is not overrun.
+
+### 5. Move Input Capture To A CPU Latest-Frame Buffer
+
+Input capture should not enqueue independent GL upload tasks.
+
+Target:
+
+```text
+DeckLink input callback
+  -> copy/coalesce latest CPU input frame
+  -> return quickly
+
+render thread frame boundary
+  -> if input version changed, upload latest frame
+  -> render using last successfully uploaded input texture
+```
+
+Deliverables:
+
+- introduce `InputFrameMailbox` with latest-frame semantics.
+- remove `RenderEngine::QueueInputFrame()` from the callback path.
+- render thread owns the upload moment.
+- if upload would exceed budget, render thread can reuse the previous input texture and record an input-upload skip.
+
+Acceptance:
+
+- input capture enabled does not create arbitrary render-thread tasks.
+- output cadence remains stable when input frames arrive.
+- telemetry separates input-frame arrival, upload count, upload skips, and upload cost.
+
+### 6. Move Preview To A Consumer Path
+
+Preview should consume the latest completed output image instead of asking the output GL context to present.
+
+Options:
+
+- CPU preview from latest system-memory output frame.
+- a separate preview GL context fed asynchronously from completed frames.
+- a low-priority render-thread blit only when output has measurable slack.
+
+Recommended first step:
+
+- use latest system-memory BGRA8 output for the window preview.
+
+Deliverables:
+
+- preview reads from latest completed/scheduled output frame copy.
+- `TryPresentPreview()` no longer queues GL work on the output render thread.
+- preview FPS throttling remains caller-side.
+
+Acceptance:
+
+- forcing preview cannot delay output rendering.
+- minimizing/focusing the window does not affect output cadence.
+
+### 7. Move Screenshot To Completed Frame Capture
+
+Screenshot should capture from the latest completed output frame unless an explicit "exact render capture" mode is requested.
+
+Deliverables:
+
+- screenshot request reads the latest system-memory output frame.
+- PNG write remains async.
+- optional diagnostic exact-GL screenshot is disabled during live output or explicitly marked disruptive.
+
+Acceptance:
+
+- screenshot request does not call `glReadPixels` on the output render context during steady-state playout.
+
+### 8. Make Shader Commits Frame-Boundary Work
+
+Prepared shader builds are CPU/background work; GL program commit is still GL work.
+
+Deliverables:
+
+- shader build queue produces `PreparedShaderBuild`.
+- render thread sees latest pending prepared build at a frame boundary.
+- commit is applied only between frames.
+- expensive commits can temporarily enter a measured "render reconfigure" state.
+
+Acceptance:
+
+- shader commits do not interleave midway through output render.
+- output timing telemetry records commit duration separately from normal render duration.
+
+### 9. Split Output Scheduling From Rendering Completely
+
+`VideoBackend` should become a playout/scheduling owner, not a render producer.
+
+Target:
+
+```text
+RenderEngine
+  -> produces completed frames at render cadence
+
+VideoBackend
+  -> schedules completed frames up to target DeckLink depth
+  -> processes completions
+  -> releases scheduled slots
+```
+
+Deliverables:
+
+- `VideoBackend` owns `SystemOutputFramePool`, or a new `SystemFrameExchange` owns it between render/video.
+- render thread publishes completed frames into the exchange.
+- video output thread schedules from the exchange.
+- no render calls exist in completion handling or scheduling paths.
+
+Acceptance:
+
+- DeckLink buffer depth changes cannot directly cause render-thread wakeups except through non-blocking availability signals.
+- render cadence can be tested without DeckLink by using a fake frame sink.
+- video scheduling can be tested without GL by using synthetic frames.
+
+### 10. Preserve The Probe As The Reference Contract
+
+The `DeckLinkRenderCadenceProbe` is now the control sample.
+
+Deliverables:
+
+- document which main-app components correspond to the probe components.
+- add a small regression checklist:
+  - render FPS near target
+  - schedule FPS near target
+  - DeckLink buffered frames stable
+  - no late/drop frames
+  - no PBO misses or readback stalls
+  - focus/minimize does not change output cadence
+
+Acceptance:
+
+- after each migration step, compare the main app telemetry against the probe's known-good behavior.
+
+## Suggested Order Of Work
+
+1. Add ownership guards and classify render methods.
+2. Move GL initialization/destruction fully onto the render thread.
+3. Introduce a render-owned cadence loop behind a feature flag.
+4. Add a frame-sink/exchange interface between render and video.
+5. Move output production from `VideoBackend` to the render cadence loop.
+6. Convert input upload to latest-frame mailbox semantics.
+7. Move preview to completed-frame consumption.
+8. Move screenshot to completed-frame capture.
+9. Convert shader commits/resets to frame-boundary mailbox commands.
+10. Remove old synchronous output render request path.
+
+## Feature Flags During Migration
+
+Use flags only to keep testing safe, not as long-term compatibility layers.
+
+Suggested flags:
+
+```text
+VST_RENDER_CADENCE_OWNER=render_thread
+VST_DISABLE_INPUT_CAPTURE=1
+VST_PREVIEW_SOURCE=system_frame
+VST_SCREENSHOT_SOURCE=system_frame
+```
+
+Remove each flag once the new behavior is proven and becomes the only supported path.
+
+## Telemetry Needed
+
+Add or preserve counters for:
+
+- render tick jitter
+- render tick overrun
+- output render duration
+- GL command mailbox depth by class
+- frame-boundary command duration
+- input upload duration and skips
+- readback queue/consume duration
+- completed system-memory frame depth
+- scheduled DeckLink frame depth
+- DeckLink actual buffered frames
+- preview frames consumed
+- screenshot requests served from system memory
+
+The key metric is whether output render starts on time. Buffer depth alone is not enough; a full buffer can still contain stale or repeated frames.
+
+## Completion Definition
+
+This work is complete when:
+
+- the output render thread owns the app GL context from initialization through shutdown
+- output rendering is driven by the render thread's selected frame cadence
+- no non-output task can run ahead of a due output frame
+- `VideoBackend` never asks the render thread to render synchronously
+- DeckLink scheduling consumes already completed system-memory frames
+- input upload, preview, screenshot, shader commits, and resets are all frame-boundary, mailbox, or consumer-side operations
+- main-app telemetry approaches the cadence probe behavior under the same output mode

docs/openapi.yaml

@@ -6,17 +6,20 @@ info:
     REST API exposed by the local Video Shader Toys control server.
 
     The API is intended for local control tools and the bundled React UI. All mutating
-    endpoints return a small action result object. Successful mutating requests also
+    endpoints return a small action result object.
-    broadcast the latest runtime state over the `/ws` WebSocket.
 
-    WebSocket state streaming is not described by OpenAPI; connect to `ws://127.0.0.1:{port}/ws`
+    RenderCadenceCompositor serves `/api/state` for snapshots and `/ws` for local
-    to receive full runtime state JSON messages whenever state changes.
+    WebSocket state updates consumed by the bundled control UI.
 servers:
   - url: http://127.0.0.1:8080
     description: Default local control server
 tags:
   - name: State
     description: Runtime state and status.
+  - name: Static
+    description: Bundled control UI and static assets served by the local host.
+  - name: Docs
+    description: OpenAPI and Swagger UI documentation served by the local host.
   - name: Layers
     description: Layer stack control.
   - name: Stack Presets
@@ -24,6 +27,146 @@ tags:
   - name: Runtime
     description: Runtime actions.
 paths:
+  /:
+    get:
+      tags: [Static]
+      summary: Serve the bundled control UI
+      description: Returns the built React control UI `index.html` from `ui/dist`.
+      operationId: getControlUiRoot
+      responses:
+        "200":
+          description: Control UI HTML.
+          content:
+            text/html:
+              schema:
+                type: string
+        "404":
+          description: UI bundle was not found.
+          content:
+            text/plain:
+              schema:
+                type: string
+  /index.html:
+    get:
+      tags: [Static]
+      summary: Serve the bundled control UI index file
+      description: Returns the built React control UI `index.html` from `ui/dist`.
+      operationId: getControlUiIndex
+      responses:
+        "200":
+          description: Control UI HTML.
+          content:
+            text/html:
+              schema:
+                type: string
+        "404":
+          description: UI bundle was not found.
+          content:
+            text/plain:
+              schema:
+                type: string
+  /assets/{assetPath}:
+    get:
+      tags: [Static]
+      summary: Serve a bundled control UI asset
+      description: Serves files from `ui/dist/assets`. The server rejects unsafe relative paths and guesses the content type from the file extension.
+      operationId: getControlUiAsset
+      parameters:
+        - name: assetPath
+          in: path
+          required: true
+          description: Relative asset path below `ui/dist/assets`.
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Static asset.
+          content:
+            text/javascript:
+              schema:
+                type: string
+            text/css:
+              schema:
+                type: string
+            image/svg+xml:
+              schema:
+                type: string
+            image/png:
+              schema:
+                type: string
+                format: binary
+            text/plain:
+              schema:
+                type: string
+        "404":
+          description: Asset was not found or the path was unsafe.
+          content:
+            text/plain:
+              schema:
+                type: string
+  /docs:
+    get:
+      tags: [Docs]
+      summary: Serve Swagger UI
+      description: Returns a small Swagger UI page pointed at `/docs/openapi.yaml`.
+      operationId: getSwaggerUi
+      responses:
+        "200":
+          description: Swagger UI HTML.
+          content:
+            text/html:
+              schema:
+                type: string
+  /docs/:
+    get:
+      tags: [Docs]
+      summary: Serve Swagger UI
+      description: Alias for `/docs`.
+      operationId: getSwaggerUiWithTrailingSlash
+      responses:
+        "200":
+          description: Swagger UI HTML.
+          content:
+            text/html:
+              schema:
+                type: string
+  /docs/openapi.yaml:
+    get:
+      tags: [Docs]
+      summary: Serve the OpenAPI document
+      operationId: getOpenApiDocumentFromDocs
+      responses:
+        "200":
+          description: OpenAPI YAML document.
+          content:
+            application/yaml:
+              schema:
+                type: string
+        "404":
+          description: OpenAPI document was not found.
+          content:
+            text/plain:
+              schema:
+                type: string
+  /openapi.yaml:
+    get:
+      tags: [Docs]
+      summary: Serve the OpenAPI document
+      description: Alias for `/docs/openapi.yaml`.
+      operationId: getOpenApiDocument
+      responses:
+        "200":
+          description: OpenAPI YAML document.
+          content:
+            application/yaml:
+              schema:
+                type: string
+        "404":
+          description: OpenAPI document was not found.
+          content:
+            text/plain:
+              schema:
+                type: string
   /api/state:
     get:
       tags: [State]
@@ -36,6 +179,24 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/RuntimeState"
+  /ws:
+    get:
+      tags: [State]
+      summary: Stream runtime state over WebSocket
+      description: |
+        Upgrades to a WebSocket connection. The server sends JSON runtime-state
+        snapshots using the same shape as `GET /api/state` whenever the serialized
+        state changes.
+      operationId: streamRuntimeState
+      responses:
+        "101":
+          description: WebSocket protocol upgrade accepted.
+        "400":
+          description: The request was not a valid WebSocket upgrade.
+          content:
+            text/plain:
+              schema:
+                type: string
   /api/layers/add:
     post:
       tags: [Layers]

tests/RenderCadenceCompositorAppConfigProviderTests.cpp

@@ -0,0 +1,128 @@
+#include "AppConfigProvider.h"
+
+#include <filesystem>
+#include <fstream>
+#include <iostream>
+#include <string>
+
+namespace
+{
+int gFailures = 0;
+
+void Expect(bool condition, const std::string& message)
+{
+	if (condition)
+		return;
+
+	++gFailures;
+	std::cerr << "FAILED: " << message << "\n";
+}
+
+std::filesystem::path WriteConfigFixture()
+{
+	const std::filesystem::path path = std::filesystem::temp_directory_path() / "render-cadence-compositor-config-test.json";
+	std::ofstream output(path, std::ios::binary);
+	output
+		<< "{\n"
+		<< "  \"shaderLibrary\": \"test-shaders\",\n"
+		<< "  \"serverPort\": 8181,\n"
+		<< "  \"oscBindAddress\": \"127.0.0.1\",\n"
+		<< "  \"oscPort\": 9100,\n"
+		<< "  \"oscSmoothing\": 0.25,\n"
+		<< "  \"inputVideoFormat\": \"720p\",\n"
+		<< "  \"inputFrameRate\": \"50\",\n"
+		<< "  \"outputVideoFormat\": \"2160p\",\n"
+		<< "  \"outputFrameRate\": \"60\",\n"
+		<< "  \"autoReload\": false,\n"
+		<< "  \"maxTemporalHistoryFrames\": 8,\n"
+		<< "  \"previewFps\": 24,\n"
+		<< "  \"enableExternalKeying\": true\n"
+		<< "}\n";
+	return path;
+}
+
+void TestLoadsRuntimeHostConfig()
+{
+	using namespace RenderCadenceCompositor;
+
+	const std::filesystem::path path = WriteConfigFixture();
+	AppConfigProvider provider;
+	std::string error;
+	const bool loaded = provider.Load(path, error);
+	const AppConfig& config = provider.Config();
+
+	Expect(loaded, "config loads");
+	Expect(error.empty(), "config load has no error");
+	Expect(provider.LoadedFromFile(), "provider records file load");
+	Expect(config.shaderLibrary == "test-shaders", "shader library loads");
+	Expect(config.http.preferredPort == 8181, "server port loads");
+	Expect(config.oscBindAddress == "127.0.0.1", "OSC bind address loads");
+	Expect(config.oscPort == 9100, "OSC port loads");
+	Expect(config.oscSmoothing == 0.25, "OSC smoothing loads");
+	Expect(config.inputVideoFormat == "720p", "input format loads");
+	Expect(config.inputFrameRate == "50", "input frame rate loads");
+	Expect(config.outputVideoFormat == "2160p", "output format loads");
+	Expect(config.outputFrameRate == "60", "output frame rate loads");
+	Expect(!config.autoReload, "auto reload loads");
+	Expect(config.maxTemporalHistoryFrames == 8, "history length loads");
+	Expect(config.previewFps == 24.0, "preview fps loads");
+	Expect(config.deckLink.externalKeyingEnabled, "external keying loads");
+
+	std::filesystem::remove(path);
+}
+
+void TestCommandLineOverrides()
+{
+	using namespace RenderCadenceCompositor;
+
+	AppConfigProvider provider;
+	const char* argv[] = {
+		"app.exe",
+		"--shader",
+		"solid-color",
+		"--port",
+		"8282"
+	};
+	provider.ApplyCommandLine(5, const_cast<char**>(argv));
+
+	const AppConfig& config = provider.Config();
+	Expect(config.runtimeShaderId == "solid-color", "shader CLI override applies");
+	Expect(config.http.preferredPort == 8282, "port CLI override applies");
+}
+
+void TestHelpers()
+{
+	using namespace RenderCadenceCompositor;
+
+	unsigned width = 0;
+	unsigned height = 0;
+	VideoFormatDimensions("720p", width, height);
+	Expect(width == 1280 && height == 720, "720p dimensions resolve");
+
+	VideoFormatDimensions("2160p", width, height);
+	Expect(width == 3840 && height == 2160, "2160p dimensions resolve");
+
+	const double duration = FrameDurationMillisecondsFromRateString("50");
+	Expect(duration > 19.9 && duration < 20.1, "frame duration parses numeric rate");
+
+	const std::filesystem::path configPath = FindConfigFile();
+	Expect(!configPath.empty(), "default config is discoverable from test working directory");
+	Expect(configPath.filename() == "runtime-host.json", "default config discovery returns runtime-host.json");
+}
+}
+
+int main()
+{
+	TestLoadsRuntimeHostConfig();
+	TestCommandLineOverrides();
+	TestHelpers();
+
+	if (gFailures != 0)
+	{
+		std::cerr << gFailures << " RenderCadenceCompositorAppConfigProvider test failure(s).\n";
+		return 1;
+	}
+
+	std::cout << "RenderCadenceCompositorAppConfigProvider tests passed.\n";
+	return 0;
+}

tests/RenderCadenceCompositorClockTests.cpp

@@ -0,0 +1,94 @@
+#include "RenderCadenceClock.h"
+
+#include <chrono>
+#include <iostream>
+
+namespace
+{
+int gFailures = 0;
+
+void Expect(bool condition, const char* message)
+{
+	if (condition)
+		return;
+
+	std::cerr << "FAIL: " << message << "\n";
+	++gFailures;
+}
+
+void TestEarlyPollWaitsWithoutAdvancing()
+{
+	using Clock = RenderCadenceClock::Clock;
+	RenderCadenceClock cadence(16.0);
+	const auto start = Clock::now();
+	cadence.Reset(start);
+
+	const auto tick = cadence.Poll(start - std::chrono::milliseconds(1));
+	Expect(!tick.due, "early poll is not due");
+	Expect(tick.sleepFor > RenderCadenceClock::Duration::zero(), "early poll returns a sleep duration");
+	Expect(cadence.OverrunCount() == 0, "early poll does not count overrun");
+	Expect(cadence.SkippedFrameCount() == 0, "early poll does not skip frames");
+}
+
+void TestDuePollRendersWithoutSkipping()
+{
+	using Clock = RenderCadenceClock::Clock;
+	RenderCadenceClock cadence(16.0);
+	const auto start = Clock::now();
+	cadence.Reset(start);
+
+	const auto tick = cadence.Poll(start);
+	Expect(tick.due, "exact cadence time is due");
+	Expect(tick.skippedFrames == 0, "exact cadence time skips no frames");
+	Expect(cadence.OverrunCount() == 0, "exact cadence time is not an overrun");
+
+	cadence.MarkRendered(start);
+	Expect(cadence.NextRenderTime() > start, "mark rendered advances next render time");
+}
+
+void TestLatePollRecordsSkippedFrames()
+{
+	using Clock = RenderCadenceClock::Clock;
+	RenderCadenceClock cadence(10.0);
+	const auto start = Clock::now();
+	cadence.Reset(start);
+
+	const auto tick = cadence.Poll(start + std::chrono::milliseconds(35));
+	Expect(tick.due, "late poll is due");
+	Expect(tick.skippedFrames == 3, "late poll records skipped frame intervals");
+	Expect(cadence.OverrunCount() == 1, "late poll records overrun");
+	Expect(cadence.SkippedFrameCount() == 3, "late poll accumulates skipped frames");
+}
+
+void TestMarkRenderedRebasesAfterLargeStall()
+{
+	using Clock = RenderCadenceClock::Clock;
+	RenderCadenceClock cadence(10.0);
+	const auto start = Clock::now();
+	cadence.Reset(start);
+
+	const auto stalled = start + std::chrono::milliseconds(100);
+	cadence.MarkRendered(stalled);
+
+	const auto next = cadence.NextRenderTime();
+	Expect(next > stalled, "large stall rebases next render time after now");
+	Expect(next - stalled <= std::chrono::milliseconds(11), "large stall rebases to roughly one frame ahead");
+}
+}
+
+int main()
+{
+	TestEarlyPollWaitsWithoutAdvancing();
+	TestDuePollRendersWithoutSkipping();
+	TestLatePollRecordsSkippedFrames();
+	TestMarkRenderedRebasesAfterLargeStall();
+
+	if (gFailures != 0)
+	{
+		std::cerr << gFailures << " cadence clock test failure(s).\n";
+		return 1;
+	}
+
+	std::cout << "RenderCadenceCompositor cadence clock tests passed.\n";
+	return 0;
+}

tests/RenderCadenceCompositorFrameExchangeTests.cpp

@@ -0,0 +1,176 @@
+#include "SystemFrameExchange.h"
+
+#include <chrono>
+#include <cstdint>
+#include <iostream>
+
+namespace
+{
+int gFailures = 0;
+
+void Expect(bool condition, const char* message)
+{
+	if (condition)
+		return;
+
+	std::cerr << "FAIL: " << message << "\n";
+	++gFailures;
+}
+
+SystemFrameExchangeConfig MakeConfig(std::size_t capacity = 2)
+{
+	SystemFrameExchangeConfig config;
+	config.width = 4;
+	config.height = 3;
+	config.pixelFormat = VideoIOPixelFormat::Bgra8;
+	config.capacity = capacity;
+	return config;
+}
+
+void TestAcquirePublishesAndSchedules()
+{
+	SystemFrameExchange exchange(MakeConfig(1));
+
+	SystemFrame frame;
+	Expect(exchange.AcquireForRender(frame), "frame can be acquired for render");
+	Expect(frame.bytes != nullptr, "acquired frame has storage");
+	Expect(frame.width == 4, "frame width is configured");
+	Expect(frame.height == 3, "frame height is configured");
+	Expect(frame.rowBytes == 16, "BGRA8 row bytes are inferred");
+	Expect(frame.pixelFormat == VideoIOPixelFormat::Bgra8, "pixel format is configured");
+
+	frame.frameIndex = 42;
+	Expect(exchange.PublishCompleted(frame), "rendering frame can be completed");
+	Expect(exchange.WaitForCompletedDepth(1, std::chrono::milliseconds(0)), "completed depth can be observed");
+
+	SystemFrame scheduled;
+	Expect(exchange.ConsumeCompletedForSchedule(scheduled), "completed frame can be scheduled");
+	Expect(scheduled.index == frame.index, "scheduled frame uses completed slot");
+	Expect(scheduled.generation == frame.generation, "scheduled frame keeps generation");
+	Expect(scheduled.frameIndex == 42, "frame index is preserved");
+
+	Expect(exchange.ReleaseScheduledByBytes(scheduled.bytes), "scheduled frame can be released by bytes");
+
+	SystemFrameExchangeMetrics metrics = exchange.Metrics();
+	Expect(metrics.freeCount == 1, "released slot returns to free");
+	Expect(metrics.completedFrames == 1, "completed metric is counted");
+	Expect(metrics.scheduledFrames == 1, "scheduled metric is counted");
+}
+
+void TestAcquireDropsOldestCompletedUnscheduled()
+{
+	SystemFrameExchange exchange(MakeConfig(2));
+
+	SystemFrame first;
+	SystemFrame second;
+	SystemFrame third;
+	Expect(exchange.AcquireForRender(first), "first frame can be acquired");
+	first.frameIndex = 1;
+	Expect(exchange.PublishCompleted(first), "first frame can be completed");
+	Expect(exchange.AcquireForRender(second), "second frame can be acquired");
+	second.frameIndex = 2;
+	Expect(exchange.PublishCompleted(second), "second frame can be completed");
+
+	Expect(exchange.AcquireForRender(third), "third acquire drops the oldest completed frame");
+	Expect(third.index == first.index, "oldest completed slot is reused");
+
+	SystemFrame scheduled;
+	Expect(exchange.ConsumeCompletedForSchedule(scheduled), "remaining completed frame can be scheduled");
+	Expect(scheduled.index == second.index, "newer completed frame survives drop");
+	Expect(scheduled.frameIndex == 2, "newer frame index survives drop");
+
+	SystemFrameExchangeMetrics metrics = exchange.Metrics();
+	Expect(metrics.completedDrops == 1, "drop metric is counted");
+	Expect(metrics.renderingCount == 1, "reused slot is rendering");
+	Expect(metrics.scheduledCount == 1, "consumed slot is scheduled");
+}
+
+void TestScheduledFramesAreNotDropped()
+{
+	SystemFrameExchange exchange(MakeConfig(1));
+
+	SystemFrame frame;
+	Expect(exchange.AcquireForRender(frame), "single frame can be acquired");
+	Expect(exchange.PublishCompleted(frame), "single frame can be completed");
+
+	SystemFrame scheduled;
+	Expect(exchange.ConsumeCompletedForSchedule(scheduled), "single frame can be scheduled");
+
+	SystemFrame extra;
+	Expect(!exchange.AcquireForRender(extra), "scheduled frame is not dropped for render acquire");
+
+	SystemFrameExchangeMetrics metrics = exchange.Metrics();
+	Expect(metrics.acquireMisses == 1, "blocked acquire miss is counted");
+	Expect(metrics.completedDrops == 0, "scheduled frame is not counted as a completed drop");
+}
+
+void TestGenerationValidationRejectsStaleFrames()
+{
+	SystemFrameExchange exchange(MakeConfig(1));
+
+	SystemFrame first;
+	Expect(exchange.AcquireForRender(first), "frame can be acquired");
+	Expect(exchange.PublishCompleted(first), "frame can be completed");
+
+	SystemFrame scheduled;
+	Expect(exchange.ConsumeCompletedForSchedule(scheduled), "frame can be scheduled");
+	Expect(exchange.ReleaseScheduledByBytes(scheduled.bytes), "frame can be released");
+
+	SystemFrame second;
+	Expect(exchange.AcquireForRender(second), "slot can be reacquired");
+	Expect(second.index == first.index, "same slot is reused");
+	Expect(second.generation != first.generation, "reacquire invalidates stale generation");
+	Expect(!exchange.PublishCompleted(first), "stale frame cannot be completed");
+}
+
+void TestPixelFormatAwareSizing()
+{
+	SystemFrameExchangeConfig config;
+	config.width = 7;
+	config.height = 2;
+	config.pixelFormat = VideoIOPixelFormat::V210;
+	config.capacity = 1;
+
+	SystemFrameExchange exchange(config);
+	SystemFrame frame;
+	Expect(exchange.AcquireForRender(frame), "v210 frame can be acquired");
+	Expect(frame.pixelFormat == VideoIOPixelFormat::V210, "v210 pixel format is preserved");
+	Expect(frame.rowBytes == static_cast<long>(VideoIORowBytes(VideoIOPixelFormat::V210, 7)), "v210 row bytes are inferred");
+
+	config.pixelFormat = VideoIOPixelFormat::Uyvy8;
+	config.rowBytes = 64;
+	exchange.Configure(config);
+	Expect(exchange.AcquireForRender(frame), "explicit row-byte frame can be acquired");
+	Expect(frame.pixelFormat == VideoIOPixelFormat::Uyvy8, "reconfigured pixel format is preserved");
+	Expect(frame.rowBytes == 64, "explicit row bytes are preserved");
+}
+
+void TestCompletedPollMissIsCounted()
+{
+	SystemFrameExchange exchange(MakeConfig(1));
+	SystemFrame frame;
+	Expect(!exchange.ConsumeCompletedForSchedule(frame), "empty completed queue cannot be consumed");
+
+	SystemFrameExchangeMetrics metrics = exchange.Metrics();
+	Expect(metrics.completedPollMisses == 1, "completed poll miss is counted");
+}
+}
+
+int main()
+{
+	TestAcquirePublishesAndSchedules();
+	TestAcquireDropsOldestCompletedUnscheduled();
+	TestScheduledFramesAreNotDropped();
+	TestGenerationValidationRejectsStaleFrames();
+	TestPixelFormatAwareSizing();
+	TestCompletedPollMissIsCounted();
+
+	if (gFailures != 0)
+	{
+		std::cerr << gFailures << " frame exchange test failure(s).\n";
+		return 1;
+	}
+
+	std::cout << "RenderCadenceCompositor frame exchange tests passed.\n";
+	return 0;
+}

tests/RenderCadenceCompositorHttpControlServerTests.cpp

@@ -0,0 +1,182 @@
+#include "HttpControlServer.h"
+
+#include <filesystem>
+#include <fstream>
+#include <iostream>
+#include <string>
+
+namespace
+{
+int gFailures = 0;
+
+void Expect(bool condition, const std::string& message)
+{
+	if (condition)
+		return;
+
+	++gFailures;
+	std::cerr << "FAILED: " << message << "\n";
+}
+
+void ExpectEquals(const std::string& actual, const std::string& expected, const std::string& message)
+{
+	if (actual == expected)
+		return;
+
+	++gFailures;
+	std::cerr << "FAILED: " << message << "\n"
+		<< "expected: " << expected << "\n"
+		<< "actual:   " << actual << "\n";
+}
+
+void TestParsesHttpRequest()
+{
+	using namespace RenderCadenceCompositor;
+
+	HttpControlServer::HttpRequest request;
+	const bool parsed = HttpControlServer::ParseHttpRequest(
+		"GET /api/state?cacheBust=1 HTTP/1.1\r\nHost: 127.0.0.1\r\n\r\n",
+		request);
+
+	Expect(parsed, "request parses");
+	ExpectEquals(request.method, "GET", "method is parsed");
+	ExpectEquals(request.path, "/api/state", "query string is stripped from path");
+	ExpectEquals(request.headers["host"], "127.0.0.1", "headers are lower-cased and trimmed");
+}
+
+void TestStateEndpointUsesCallback()
+{
+	using namespace RenderCadenceCompositor;
+
+	HttpControlServer server;
+	HttpControlServerCallbacks callbacks;
+	callbacks.getStateJson = []() { return std::string("{\"ok\":true}"); };
+	server.SetCallbacksForTest(callbacks);
+
+	HttpControlServer::HttpRequest request;
+	request.method = "GET";
+	request.path = "/api/state";
+
+	const HttpControlServer::HttpResponse response = server.RouteRequestForTest(request);
+	ExpectEquals(response.status, "200 OK", "state endpoint succeeds");
+	ExpectEquals(response.contentType, "application/json", "state endpoint is JSON");
+	ExpectEquals(response.body, "{\"ok\":true}", "state endpoint returns callback JSON");
+}
+
+void TestWebSocketAcceptKey()
+{
+	using namespace RenderCadenceCompositor;
+
+	const std::string acceptKey = HttpControlServer::WebSocketAcceptKey("dGhlIHNhbXBsZSBub25jZQ==");
+	ExpectEquals(acceptKey, "s3pPLMBiTxaQ9kYGzzhZRbK+xOo=", "WebSocket accept key matches RFC example");
+}
+
+void TestRootServesUiIndex()
+{
+	using namespace RenderCadenceCompositor;
+
+	const std::filesystem::path root = std::filesystem::temp_directory_path() / "render-cadence-compositor-ui-test";
+	std::filesystem::create_directories(root);
+	{
+		std::ofstream output(root / "index.html", std::ios::binary);
+		output << "<!doctype html><div id=\"root\"></div>";
+	}
+
+	HttpControlServer server;
+	HttpControlServer::HttpRequest request;
+	request.method = "GET";
+	request.path = "/";
+
+	server.SetRootsForTest(root, std::filesystem::path());
+	const HttpControlServer::HttpResponse response = server.RouteRequestForTest(request);
+
+	ExpectEquals(response.status, "200 OK", "root endpoint serves UI index");
+	ExpectEquals(response.contentType, "text/html", "UI index content type is html");
+	Expect(response.body.find("root") != std::string::npos, "UI index body is returned");
+
+	std::filesystem::remove_all(root);
+}
+
+void TestKnownPostEndpointReturnsActionError()
+{
+	using namespace RenderCadenceCompositor;
+
+	HttpControlServer server;
+	HttpControlServer::HttpRequest request;
+	request.method = "POST";
+	request.path = "/api/layers/add";
+	request.body = "{\"shaderId\":\"happy-accident\"}";
+
+	const HttpControlServer::HttpResponse response = server.RouteRequestForTest(request);
+	ExpectEquals(response.status, "400 Bad Request", "unimplemented post returns OpenAPI action error status");
+	ExpectEquals(response.contentType, "application/json", "unimplemented post returns JSON");
+	Expect(response.body.find("\"ok\":false") != std::string::npos, "unimplemented post reports ok false");
+	Expect(response.body.find("not implemented") != std::string::npos, "unimplemented post reports diagnostic");
+}
+
+void TestLayerPostEndpointsUseCallbacks()
+{
+	using namespace RenderCadenceCompositor;
+
+	HttpControlServer server;
+	HttpControlServerCallbacks callbacks;
+	callbacks.addLayer = [](const std::string& body) {
+		Expect(body.find("solid") != std::string::npos, "add callback receives request body");
+		return ControlActionResult{ true, std::string() };
+	};
+	callbacks.removeLayer = [](const std::string& body) {
+		Expect(body.find("runtime-layer-1") != std::string::npos, "remove callback receives request body");
+		return ControlActionResult{ false, "Unknown layer id." };
+	};
+	server.SetCallbacksForTest(callbacks);
+
+	HttpControlServer::HttpRequest addRequest;
+	addRequest.method = "POST";
+	addRequest.path = "/api/layers/add";
+	addRequest.body = "{\"shaderId\":\"solid\"}";
+	const HttpControlServer::HttpResponse addResponse = server.RouteRequestForTest(addRequest);
+	ExpectEquals(addResponse.status, "200 OK", "add layer callback success returns 200");
+	Expect(addResponse.body.find("\"ok\":true") != std::string::npos, "add layer callback returns action success");
+
+	HttpControlServer::HttpRequest removeRequest;
+	removeRequest.method = "POST";
+	removeRequest.path = "/api/layers/remove";
+	removeRequest.body = "{\"layerId\":\"runtime-layer-1\"}";
+	const HttpControlServer::HttpResponse removeResponse = server.RouteRequestForTest(removeRequest);
+	ExpectEquals(removeResponse.status, "400 Bad Request", "remove layer callback failure returns 400");
+	Expect(removeResponse.body.find("Unknown layer id.") != std::string::npos, "remove layer callback returns diagnostic");
+}
+
+void TestUnknownEndpointReturns404()
+{
+	using namespace RenderCadenceCompositor;
+
+	HttpControlServer server;
+	HttpControlServer::HttpRequest request;
+	request.method = "GET";
+	request.path = "/api/nope";
+
+	const HttpControlServer::HttpResponse response = server.RouteRequestForTest(request);
+	ExpectEquals(response.status, "404 Not Found", "unknown endpoint returns 404");
+}
+}
+
+int main()
+{
+	TestParsesHttpRequest();
+	TestStateEndpointUsesCallback();
+	TestWebSocketAcceptKey();
+	TestRootServesUiIndex();
+	TestKnownPostEndpointReturnsActionError();
+	TestLayerPostEndpointsUseCallbacks();
+	TestUnknownEndpointReturns404();
+
+	if (gFailures != 0)
+	{
+		std::cerr << gFailures << " RenderCadenceCompositorHttpControlServer test failure(s).\n";
+		return 1;
+	}
+
+	std::cout << "RenderCadenceCompositorHttpControlServer tests passed.\n";
+	return 0;
+}

tests/RenderCadenceCompositorJsonWriterTests.cpp

@@ -0,0 +1,123 @@
+#include "JsonWriter.h"
+
+#include <iostream>
+#include <stdexcept>
+#include <string>
+
+namespace
+{
+int gFailures = 0;
+
+void Expect(bool condition, const std::string& message)
+{
+	if (condition)
+		return;
+
+	++gFailures;
+	std::cerr << "FAILED: " << message << "\n";
+}
+
+void ExpectEquals(const std::string& actual, const std::string& expected, const std::string& message)
+{
+	if (actual == expected)
+		return;
+
+	++gFailures;
+	std::cerr << "FAILED: " << message << "\n"
+		<< "expected: " << expected << "\n"
+		<< "actual:   " << actual << "\n";
+}
+
+void TestEscapesStrings()
+{
+	using RenderCadenceCompositor::JsonWriter;
+
+	ExpectEquals(
+		JsonWriter::EscapeString("quote\" slash\\ newline\n tab\t"),
+		"quote\\\" slash\\\\ newline\\n tab\\t",
+		"string escape handles common escaped characters");
+
+	std::string control;
+	control.push_back(static_cast<char>(0x01));
+	ExpectEquals(JsonWriter::EscapeString(control), "\\u0001", "string escape handles control characters");
+}
+
+void TestObjectSerialization()
+{
+	using RenderCadenceCompositor::JsonWriter;
+
+	JsonWriter writer;
+	writer.BeginObject();
+	writer.KeyString("name", "cadence");
+	writer.KeyDouble("renderFps", 59.94);
+	writer.KeyBool("healthy", true);
+	writer.KeyNull("error");
+	writer.EndObject();
+
+	ExpectEquals(
+		writer.StringValue(),
+		"{\"name\":\"cadence\",\"renderFps\":59.94,\"healthy\":true,\"error\":null}",
+		"object serialization is compact and ordered");
+}
+
+void TestNestedArrays()
+{
+	using RenderCadenceCompositor::JsonWriter;
+
+	JsonWriter writer;
+	writer.BeginObject();
+	writer.Key("levels");
+	writer.BeginArray();
+	writer.String("log");
+	writer.String("warning");
+	writer.String("error");
+	writer.EndArray();
+	writer.Key("counts");
+	writer.BeginObject();
+	writer.KeyUInt("queued", 3);
+	writer.KeyInt("delta", -1);
+	writer.EndObject();
+	writer.EndObject();
+
+	ExpectEquals(
+		writer.StringValue(),
+		"{\"levels\":[\"log\",\"warning\",\"error\"],\"counts\":{\"queued\":3,\"delta\":-1}}",
+		"nested arrays and objects serialize correctly");
+}
+
+void TestMisuseThrows()
+{
+	using RenderCadenceCompositor::JsonWriter;
+
+	JsonWriter writer;
+	bool threw = false;
+	try
+	{
+		writer.BeginObject();
+		writer.Key("missing");
+		writer.EndObject();
+	}
+	catch (const std::logic_error&)
+	{
+		threw = true;
+	}
+	Expect(threw, "ending an object with a key missing a value throws");
+}
+}
+
+int main()
+{
+	TestEscapesStrings();
+	TestObjectSerialization();
+	TestNestedArrays();
+	TestMisuseThrows();
+
+	if (gFailures != 0)
+	{
+		std::cerr << gFailures << " RenderCadenceCompositorJsonWriter test failure(s).\n";
+		return 1;
+	}
+
+	std::cout << "RenderCadenceCompositorJsonWriter tests passed.\n";
+	return 0;
+}

tests/RenderCadenceCompositorLoggerTests.cpp

@@ -0,0 +1,88 @@
+#include "Logger.h"
+
+#include <chrono>
+#include <iostream>
+#include <string>
+#include <thread>
+
+namespace
+{
+int gFailures = 0;
+
+void Expect(bool condition, const std::string& message)
+{
+	if (condition)
+		return;
+
+	++gFailures;
+	std::cerr << "FAILED: " << message << "\n";
+}
+
+void TestLevelNames()
+{
+	using namespace RenderCadenceCompositor;
+	Expect(std::string(LogLevelName(LogLevel::Log)) == "log", "log level name");
+	Expect(std::string(LogLevelName(LogLevel::Warning)) == "warning", "warning level name");
+	Expect(std::string(LogLevelName(LogLevel::Error)) == "error", "error level name");
+}
+
+void TestLevelFiltering()
+{
+	using namespace RenderCadenceCompositor;
+
+	LoggerConfig config;
+	config.minimumLevel = LogLevel::Warning;
+	config.writeToConsole = false;
+	config.writeToDebugOutput = false;
+	config.writeToFile = false;
+	config.maxQueuedMessages = 16;
+
+	Logger& logger = Logger::Instance();
+	logger.Start(config);
+	logger.Write(LogLevel::Log, "test", "filtered");
+	logger.Write(LogLevel::Warning, "test", "kept");
+	logger.Write(LogLevel::Error, "test", "kept");
+	logger.Stop();
+
+	const LoggerCounters counters = logger.Counters();
+	Expect(counters.queued == 2, "logger queues only messages at or above minimum level");
+	Expect(counters.written == 2, "logger writes queued messages before stop returns");
+	Expect(counters.dropped == 0, "logger does not drop under queue capacity");
+}
+
+void TestTryWriteDropsWhenQueueIsFull()
+{
+	using namespace RenderCadenceCompositor;
+
+	LoggerConfig config;
+	config.minimumLevel = LogLevel::Log;
+	config.writeToConsole = false;
+	config.writeToDebugOutput = false;
+	config.writeToFile = false;
+	config.maxQueuedMessages = 0;
+
+	Logger& logger = Logger::Instance();
+	logger.Start(config);
+
+	const bool sawDrop = !logger.TryWrite(LogLevel::Log, "test", "message");
+	logger.Stop();
+
+	Expect(sawDrop || logger.Counters().dropped > 0, "try-write reports or counts queue pressure");
+}
+}
+
+int main()
+{
+	TestLevelNames();
+	TestLevelFiltering();
+	TestTryWriteDropsWhenQueueIsFull();
+
+	if (gFailures != 0)
+	{
+		std::cerr << gFailures << " RenderCadenceCompositorLogger test failure(s).\n";
+		return 1;
+	}
+
+	std::cout << "RenderCadenceCompositorLogger tests passed.\n";
+	return 0;
+}

tests/RenderCadenceCompositorRuntimeLayerModelTests.cpp

@@ -0,0 +1,163 @@
+#include "RuntimeLayerModel.h"
+
+#include <chrono>
+#include <filesystem>
+#include <fstream>
+#include <iostream>
+#include <string>
+
+namespace
+{
+int gFailures = 0;
+
+void Expect(bool condition, const std::string& message)
+{
+	if (condition)
+		return;
+
+	++gFailures;
+	std::cerr << "FAIL: " << message << "\n";
+}
+
+std::filesystem::path MakeTestRoot()
+{
+	const auto stamp = std::chrono::steady_clock::now().time_since_epoch().count();
+	const std::filesystem::path root = std::filesystem::temp_directory_path() / ("render-cadence-layer-model-tests-" + std::to_string(stamp));
+	std::filesystem::create_directories(root);
+	return root;
+}
+
+void WriteFile(const std::filesystem::path& path, const std::string& contents)
+{
+	std::filesystem::create_directories(path.parent_path());
+	std::ofstream output(path, std::ios::binary);
+	output << contents;
+}
+
+RenderCadenceCompositor::SupportedShaderCatalog MakeCatalog(std::filesystem::path& root)
+{
+	root = MakeTestRoot();
+	WriteFile(root / "solid" / "shader.slang", "float4 shadeVideo(float2 uv) { return float4(uv, 0.0, 1.0); }\n");
+	WriteFile(root / "solid" / "shader.json", R"({
+		"id": "solid",
+		"name": "Solid",
+		"description": "Solid test shader",
+		"category": "Tests",
+		"entryPoint": "shadeVideo",
+		"parameters": [
+			{ "id": "gain", "label": "Gain", "type": "float", "default": 0.5 }
+		]
+	})");
+
+	RenderCadenceCompositor::SupportedShaderCatalog catalog;
+	std::string error;
+	Expect(catalog.Load(root, 4, error), error.empty() ? "catalog loads test shader" : error);
+	return catalog;
+}
+
+void TestSingleLayerLifecycle()
+{
+	std::filesystem::path root;
+	RenderCadenceCompositor::SupportedShaderCatalog catalog = MakeCatalog(root);
+
+	RenderCadenceCompositor::RuntimeLayerModel model;
+	std::string error;
+	Expect(model.InitializeSingleLayer(catalog, "solid", error), "model initializes a supported startup shader");
+	Expect(model.FirstLayerId() == "runtime-layer-1", "startup layer id is stable");
+
+	Expect(model.MarkBuildStarted(model.FirstLayerId(), "build started", error), "build start updates the layer");
+	RenderCadenceCompositor::RuntimeLayerModelSnapshot snapshot = model.Snapshot();
+	Expect(snapshot.displayLayers.size() == 1, "snapshot exposes the display layer");
+	Expect(snapshot.displayLayers[0].buildState == RenderCadenceCompositor::RuntimeLayerBuildState::Pending, "started layer is pending");
+	Expect(!snapshot.displayLayers[0].renderReady, "started layer is not render-ready yet");
+
+	RuntimeShaderArtifact artifact;
+	artifact.shaderId = "solid";
+	artifact.displayName = "Solid";
+	artifact.fragmentShaderSource = "void main(){}";
+	artifact.message = "build ready";
+	Expect(model.MarkBuildReady(artifact, error), "ready artifact updates the matching layer");
+
+	snapshot = model.Snapshot();
+	Expect(snapshot.compileSucceeded, "ready layer reports compile success");
+	Expect(snapshot.displayLayers[0].buildState == RenderCadenceCompositor::RuntimeLayerBuildState::Ready, "ready layer is marked ready");
+	Expect(snapshot.displayLayers[0].renderReady, "ready layer exposes render readiness");
+	Expect(snapshot.renderLayers.size() == 1, "ready layer produces one render layer artifact");
+	Expect(snapshot.renderLayers[0].artifact.shaderId == "solid", "render layer carries the artifact");
+
+	std::filesystem::remove_all(root);
+}
+
+void TestRejectsUnsupportedStartupShader()
+{
+	std::filesystem::path root;
+	RenderCadenceCompositor::SupportedShaderCatalog catalog = MakeCatalog(root);
+
+	RenderCadenceCompositor::RuntimeLayerModel model;
+	std::string error;
+	Expect(!model.InitializeSingleLayer(catalog, "missing", error), "model rejects unsupported shader ids");
+	Expect(!error.empty(), "unsupported shader rejection explains the problem");
+	Expect(model.Snapshot().displayLayers.empty(), "rejected startup shader leaves no display layer");
+
+	std::filesystem::remove_all(root);
+}
+
+void TestBuildFailureStaysDisplaySide()
+{
+	std::filesystem::path root;
+	RenderCadenceCompositor::SupportedShaderCatalog catalog = MakeCatalog(root);
+
+	RenderCadenceCompositor::RuntimeLayerModel model;
+	std::string error;
+	Expect(model.InitializeSingleLayer(catalog, "solid", error), "model initializes for failure test");
+	Expect(model.MarkBuildFailed(model.FirstLayerId(), "compile failed", error), "build failure updates the layer");
+
+	const RenderCadenceCompositor::RuntimeLayerModelSnapshot snapshot = model.Snapshot();
+	Expect(!snapshot.compileSucceeded, "failed layer reports compile failure");
+	Expect(snapshot.displayLayers[0].buildState == RenderCadenceCompositor::RuntimeLayerBuildState::Failed, "failed layer is marked failed");
+	Expect(!snapshot.displayLayers[0].renderReady, "failed layer is not render-ready");
+	Expect(snapshot.renderLayers.empty(), "failed layer does not produce a render artifact");
+
+	std::filesystem::remove_all(root);
+}
+
+void TestAddAndRemoveLayers()
+{
+	std::filesystem::path root;
+	RenderCadenceCompositor::SupportedShaderCatalog catalog = MakeCatalog(root);
+
+	RenderCadenceCompositor::RuntimeLayerModel model;
+	std::string error;
+	std::string firstLayerId;
+	std::string secondLayerId;
+	Expect(model.AddLayer(catalog, "solid", firstLayerId, error), "first layer can be added");
+	Expect(model.AddLayer(catalog, "solid", secondLayerId, error), "second layer can be added");
+	Expect(firstLayerId != secondLayerId, "added layers receive distinct ids");
+	Expect(model.Snapshot().displayLayers.size() == 2, "added layers appear in display snapshot");
+
+	Expect(model.RemoveLayer(firstLayerId, error), "existing layer can be removed");
+	RenderCadenceCompositor::RuntimeLayerModelSnapshot snapshot = model.Snapshot();
+	Expect(snapshot.displayLayers.size() == 1, "removed layer leaves snapshot");
+	Expect(snapshot.displayLayers[0].id == secondLayerId, "remaining layer identity is preserved");
+	Expect(!model.RemoveLayer(firstLayerId, error), "removed layer cannot be removed twice");
+
+	std::filesystem::remove_all(root);
+}
+}
+
+int main()
+{
+	TestSingleLayerLifecycle();
+	TestRejectsUnsupportedStartupShader();
+	TestBuildFailureStaysDisplaySide();
+	TestAddAndRemoveLayers();
+
+	if (gFailures != 0)
+	{
+		std::cerr << gFailures << " RenderCadenceCompositorRuntimeLayerModel test failure(s).\n";
+		return 1;
+	}
+
+	std::cout << "RenderCadenceCompositorRuntimeLayerModel tests passed.\n";
+	return 0;
+}

tests/RenderCadenceCompositorRuntimeShaderParamsTests.cpp

@@ -0,0 +1,110 @@
+#include "RuntimeShaderParams.h"
+
+#include <cstring>
+#include <iostream>
+#include <string>
+#include <vector>
+
+namespace
+{
+void Expect(bool condition, const char* message)
+{
+	if (!condition)
+	{
+		std::cerr << "FAILED: " << message << "\n";
+		std::exit(1);
+	}
+}
+
+float ReadFloat(const std::vector<unsigned char>& buffer, std::size_t offset)
+{
+	float value = 0.0f;
+	std::memcpy(&value, buffer.data() + offset, sizeof(value));
+	return value;
+}
+
+int ReadInt(const std::vector<unsigned char>& buffer, std::size_t offset)
+{
+	int value = 0;
+	std::memcpy(&value, buffer.data() + offset, sizeof(value));
+	return value;
+}
+
+ShaderParameterDefinition FloatParam(const std::string& id, double defaultValue)
+{
+	ShaderParameterDefinition definition;
+	definition.id = id;
+	definition.label = id;
+	definition.type = ShaderParameterType::Float;
+	definition.defaultNumbers = { defaultValue };
+	return definition;
+}
+
+ShaderParameterDefinition Vec2Param()
+{
+	ShaderParameterDefinition definition;
+	definition.id = "offset";
+	definition.label = "Offset";
+	definition.type = ShaderParameterType::Vec2;
+	definition.defaultNumbers = { 2.0, 3.0 };
+	return definition;
+}
+
+ShaderParameterDefinition ColorParam()
+{
+	ShaderParameterDefinition definition;
+	definition.id = "tint";
+	definition.label = "Tint";
+	definition.type = ShaderParameterType::Color;
+	definition.defaultNumbers = { 0.25, 0.5, 0.75, 1.0 };
+	return definition;
+}
+
+ShaderParameterDefinition BoolParam()
+{
+	ShaderParameterDefinition definition;
+	definition.id = "enabled";
+	definition.label = "Enabled";
+	definition.type = ShaderParameterType::Boolean;
+	definition.defaultBoolean = true;
+	return definition;
+}
+
+ShaderParameterDefinition EnumParam()
+{
+	ShaderParameterDefinition definition;
+	definition.id = "mode";
+	definition.label = "Mode";
+	definition.type = ShaderParameterType::Enum;
+	definition.defaultEnumValue = "hard";
+	definition.enumOptions = { { "soft", "Soft" }, { "hard", "Hard" } };
+	return definition;
+}
+}
+
+int main()
+{
+	RuntimeShaderArtifact artifact;
+	artifact.parameterDefinitions.push_back(FloatParam("gain", 0.5));
+	artifact.parameterDefinitions.push_back(Vec2Param());
+	artifact.parameterDefinitions.push_back(ColorParam());
+	artifact.parameterDefinitions.push_back(BoolParam());
+	artifact.parameterDefinitions.push_back(EnumParam());
+
+	const std::vector<unsigned char> buffer = BuildRuntimeShaderGlobalParamsStd140(artifact, 120, 1920, 1080);
+
+	Expect(buffer.size() == 112, "runtime shader params block keeps expected std140 size");
+	Expect(ReadFloat(buffer, 0) == 2.0f, "time is derived from frame index at 60 fps");
+	Expect(ReadFloat(buffer, 8) == 1920.0f, "input width is packed after std140 vec2 alignment");
+	Expect(ReadFloat(buffer, 12) == 1080.0f, "input height is packed after std140 vec2 alignment");
+	Expect(ReadFloat(buffer, 60) == 0.5f, "float default parameter is packed");
+	Expect(ReadFloat(buffer, 64) == 2.0f, "vec2 default x is packed");
+	Expect(ReadFloat(buffer, 68) == 3.0f, "vec2 default y is packed");
+	Expect(ReadFloat(buffer, 80) == 0.25f, "color default red is packed on vec4 alignment");
+	Expect(ReadFloat(buffer, 92) == 1.0f, "color default alpha is packed");
+	Expect(ReadInt(buffer, 96) == 1, "bool default is packed as int");
+	Expect(ReadInt(buffer, 100) == 1, "enum default is packed as selected option index");
+
+	std::cout << "RenderCadenceCompositorRuntimeShaderParams tests passed.\n";
+	return 0;
+}

tests/RenderCadenceCompositorRuntimeStateJsonTests.cpp

@@ -0,0 +1,112 @@
+#include "RuntimeStateJson.h"
+
+#include <chrono>
+#include <filesystem>
+#include <fstream>
+#include <iostream>
+#include <string>
+
+namespace
+{
+int gFailures = 0;
+
+void ExpectContains(const std::string& text, const std::string& fragment, const std::string& message)
+{
+	if (text.find(fragment) != std::string::npos)
+		return;
+
+	++gFailures;
+	std::cerr << "FAIL: " << message << "\n";
+}
+
+std::filesystem::path MakeTestRoot()
+{
+	const auto stamp = std::chrono::steady_clock::now().time_since_epoch().count();
+	const std::filesystem::path root = std::filesystem::temp_directory_path() / ("render-cadence-state-json-tests-" + std::to_string(stamp));
+	std::filesystem::create_directories(root);
+	return root;
+}
+
+void WriteFile(const std::filesystem::path& path, const std::string& contents)
+{
+	std::filesystem::create_directories(path.parent_path());
+	std::ofstream output(path, std::ios::binary);
+	output << contents;
+}
+}
+
+int main()
+{
+	RenderCadenceCompositor::AppConfig config = RenderCadenceCompositor::DefaultAppConfig();
+	config.outputVideoFormat = "1080p";
+	config.outputFrameRate = "59.94";
+
+	RenderCadenceCompositor::CadenceTelemetrySnapshot telemetry;
+	telemetry.renderFps = 59.94;
+	telemetry.shaderBuildsCommitted = 1;
+
+	const std::filesystem::path root = MakeTestRoot();
+	WriteFile(root / "solid-color" / "shader.slang", "float4 shadeVideo(float2 uv) { return float4(uv, 0.0, 1.0); }\n");
+	WriteFile(root / "solid-color" / "shader.json", R"({
+		"id": "solid-color",
+		"name": "Solid Color",
+		"description": "A single color shader.",
+		"category": "Generator",
+		"entryPoint": "shadeVideo",
+		"parameters": [
+			{
+				"id": "color",
+				"label": "Color",
+				"description": "Output color.",
+				"type": "color",
+				"default": [1.0, 0.25, 0.5, 1.0],
+				"min": [0.0, 0.0, 0.0, 0.0],
+				"max": [1.0, 1.0, 1.0, 1.0],
+				"step": [0.01, 0.01, 0.01, 0.01]
+			}
+		]
+	})");
+
+	RenderCadenceCompositor::SupportedShaderCatalog shaderCatalog;
+	std::string error;
+	ExpectContains(shaderCatalog.Load(root, 4, error) ? "loaded" : error, "loaded", "test shader catalog should load");
+
+	RenderCadenceCompositor::RuntimeLayerModel layerModel;
+	layerModel.InitializeSingleLayer(shaderCatalog, "solid-color", error);
+	RuntimeShaderArtifact artifact;
+	artifact.shaderId = "solid-color";
+	artifact.displayName = "Solid Color";
+	artifact.fragmentShaderSource = "void main(){}";
+	artifact.message = "Runtime shader committed.";
+	layerModel.MarkBuildReady(artifact, error);
+	const RenderCadenceCompositor::RuntimeLayerModelSnapshot layerSnapshot = layerModel.Snapshot();
+
+	const std::string json = RenderCadenceCompositor::RuntimeStateToJson(RenderCadenceCompositor::RuntimeStateJsonInput{
+		config,
+		telemetry,
+		8080,
+		true,
+		"DeckLink scheduled output running.",
+		shaderCatalog,
+		layerSnapshot
+	});
+
+	ExpectContains(json, "\"shaders\":[{\"id\":\"solid-color\"", "state JSON should include supported shaders");
+	ExpectContains(json, "\"layerCount\":1", "state JSON should expose the display layer count");
+	ExpectContains(json, "\"layers\":[{\"id\":\"runtime-layer-1\"", "state JSON should expose the active display layer");
+	ExpectContains(json, "\"parameters\":[{\"id\":\"color\"", "state JSON should expose active shader parameters");
+	ExpectContains(json, "\"type\":\"color\"", "state JSON should serialize parameter types for the UI");
+	ExpectContains(json, "\"width\":1920", "state JSON should expose output width");
+	ExpectContains(json, "\"height\":1080", "state JSON should expose output height");
+
+	std::filesystem::remove_all(root);
+
+	if (gFailures != 0)
+	{
+		std::cerr << gFailures << " RenderCadenceCompositorRuntimeStateJson test failure(s).\n";
+		return 1;
+	}
+
+	std::cout << "RenderCadenceCompositorRuntimeStateJson tests passed.\n";
+	return 0;
+}

tests/RenderCadenceCompositorSupportedShaderCatalogTests.cpp

@@ -0,0 +1,113 @@
+#include "SupportedShaderCatalog.h"
+
+#include <iostream>
+#include <string>
+
+namespace
+{
+int gFailures = 0;
+
+void Expect(bool condition, const std::string& message)
+{
+	if (condition)
+		return;
+
+	++gFailures;
+	std::cerr << "FAIL: " << message << "\n";
+}
+
+ShaderPackage MakeSinglePassPackage()
+{
+	ShaderPackage shaderPackage;
+	shaderPackage.id = "supported";
+	ShaderPassDefinition pass;
+	pass.id = "main";
+	pass.entryPoint = "mainImage";
+	shaderPackage.passes.push_back(pass);
+	return shaderPackage;
+}
+
+void SupportsSinglePassStatelessPackage()
+{
+	const ShaderPackage shaderPackage = MakeSinglePassPackage();
+	const RenderCadenceCompositor::ShaderSupportResult result =
+		RenderCadenceCompositor::CheckStatelessSinglePassShaderSupport(shaderPackage);
+
+	Expect(result.supported, "single-pass stateless packages should be supported");
+	Expect(result.reason.empty(), "supported packages should not report a rejection reason");
+}
+
+void RejectsMultipassPackage()
+{
+	ShaderPackage shaderPackage = MakeSinglePassPackage();
+	ShaderPassDefinition secondPass;
+	secondPass.id = "second";
+	secondPass.entryPoint = "mainImage";
+	shaderPackage.passes.push_back(secondPass);
+
+	const RenderCadenceCompositor::ShaderSupportResult result =
+		RenderCadenceCompositor::CheckStatelessSinglePassShaderSupport(shaderPackage);
+
+	Expect(!result.supported, "multipass packages should be rejected");
+	Expect(result.reason.find("single-pass") != std::string::npos, "multipass rejection should explain the single-pass limit");
+}
+
+void RejectsTemporalPackage()
+{
+	ShaderPackage shaderPackage = MakeSinglePassPackage();
+	shaderPackage.temporal.enabled = true;
+
+	const RenderCadenceCompositor::ShaderSupportResult result =
+		RenderCadenceCompositor::CheckStatelessSinglePassShaderSupport(shaderPackage);
+
+	Expect(!result.supported, "temporal packages should be rejected");
+	Expect(result.reason.find("temporal") != std::string::npos, "temporal rejection should mention temporal storage");
+}
+
+void RejectsTextureAssets()
+{
+	ShaderPackage shaderPackage = MakeSinglePassPackage();
+	ShaderTextureAsset asset;
+	asset.id = "lut";
+	shaderPackage.textureAssets.push_back(asset);
+
+	const RenderCadenceCompositor::ShaderSupportResult result =
+		RenderCadenceCompositor::CheckStatelessSinglePassShaderSupport(shaderPackage);
+
+	Expect(!result.supported, "texture-backed packages should be rejected for now");
+	Expect(result.reason.find("texture") != std::string::npos, "texture rejection should mention texture assets");
+}
+
+void RejectsTextParameters()
+{
+	ShaderPackage shaderPackage = MakeSinglePassPackage();
+	ShaderParameterDefinition parameter;
+	parameter.id = "caption";
+	parameter.type = ShaderParameterType::Text;
+	shaderPackage.parameters.push_back(parameter);
+
+	const RenderCadenceCompositor::ShaderSupportResult result =
+		RenderCadenceCompositor::CheckStatelessSinglePassShaderSupport(shaderPackage);
+
+	Expect(!result.supported, "text-parameter packages should be rejected for now");
+	Expect(result.reason.find("text") != std::string::npos, "text rejection should mention text parameters");
+}
+}
+
+int main()
+{
+	SupportsSinglePassStatelessPackage();
+	RejectsMultipassPackage();
+	RejectsTemporalPackage();
+	RejectsTextureAssets();
+	RejectsTextParameters();
+
+	if (gFailures != 0)
+	{
+		std::cerr << gFailures << " RenderCadenceCompositorSupportedShaderCatalog test failure(s).\n";
+		return 1;
+	}
+
+	std::cout << "RenderCadenceCompositorSupportedShaderCatalog tests passed.\n";
+	return 0;
+}

tests/RenderCadenceCompositorTelemetryTests.cpp

@@ -0,0 +1,195 @@
+#include "CadenceTelemetry.h"
+#include "CadenceTelemetryJson.h"
+
+#include <chrono>
+#include <cstdint>
+#include <iostream>
+#include <thread>
+
+namespace
+{
+int gFailures = 0;
+
+void Expect(bool condition, const char* message)
+{
+	if (condition)
+		return;
+
+	std::cerr << "FAIL: " << message << "\n";
+	++gFailures;
+}
+
+struct FakeExchangeMetrics
+{
+	std::size_t freeCount = 0;
+	std::size_t completedCount = 0;
+	std::size_t scheduledCount = 0;
+	uint64_t completedFrames = 0;
+	uint64_t scheduledFrames = 0;
+};
+
+struct FakeExchange
+{
+	FakeExchangeMetrics metrics;
+	FakeExchangeMetrics Metrics() const { return metrics; }
+};
+
+struct FakeOutputThreadMetrics
+{
+	uint64_t completedPollMisses = 0;
+	uint64_t scheduleFailures = 0;
+};
+
+struct FakeOutputThread
+{
+	FakeOutputThreadMetrics metrics;
+	FakeOutputThreadMetrics Metrics() const { return metrics; }
+};
+
+struct FakeOutputMetrics
+{
+	uint64_t completions = 0;
+	uint64_t displayedLate = 0;
+	uint64_t dropped = 0;
+	uint64_t scheduleFailures = 0;
+	bool actualBufferedFramesAvailable = false;
+	uint64_t actualBufferedFrames = 0;
+	double scheduleCallMilliseconds = 0.0;
+};
+
+struct FakeOutput
+{
+	FakeOutputMetrics metrics;
+	FakeOutputMetrics Metrics() const { return metrics; }
+};
+
+struct FakeRenderThreadMetrics
+{
+	uint64_t shaderBuildsCommitted = 0;
+	uint64_t shaderBuildFailures = 0;
+};
+
+struct FakeRenderThread
+{
+	FakeRenderThreadMetrics metrics;
+	FakeRenderThreadMetrics GetMetrics() const { return metrics; }
+};
+
+void TestTelemetrySamplesCompletedPollMissesAndShaderCounts()
+{
+	RenderCadenceCompositor::CadenceTelemetry telemetry;
+	FakeExchange exchange;
+	exchange.metrics.freeCount = 7;
+	exchange.metrics.completedCount = 1;
+	exchange.metrics.scheduledCount = 4;
+	exchange.metrics.completedFrames = 100;
+	exchange.metrics.scheduledFrames = 96;
+
+	FakeOutput output;
+	output.metrics.actualBufferedFramesAvailable = true;
+	output.metrics.actualBufferedFrames = 4;
+
+	FakeOutputThread outputThread;
+	outputThread.metrics.completedPollMisses = 12;
+	outputThread.metrics.scheduleFailures = 0;
+
+	FakeRenderThread renderThread;
+	renderThread.metrics.shaderBuildsCommitted = 1;
+	renderThread.metrics.shaderBuildFailures = 0;
+
+	const auto snapshot = telemetry.Sample(exchange, output, outputThread, renderThread);
+	Expect(snapshot.freeFrames == 7, "free frame count is sampled");
+	Expect(snapshot.completedFrames == 1, "completed frame count is sampled");
+	Expect(snapshot.scheduledFrames == 4, "scheduled frame count is sampled");
+	Expect(snapshot.completedPollMisses == 12, "completed poll misses are sampled");
+	Expect(snapshot.shaderBuildsCommitted == 1, "shader committed count is sampled");
+	Expect(snapshot.shaderBuildFailures == 0, "shader failure count is sampled");
+	Expect(snapshot.deckLinkBufferedAvailable, "buffer telemetry availability is sampled");
+	Expect(snapshot.deckLinkBuffered == 4, "buffer depth is sampled");
+}
+
+void TestTelemetryComputesRatesFromDeltas()
+{
+	RenderCadenceCompositor::CadenceTelemetry telemetry;
+	FakeExchange exchange;
+	FakeOutput output;
+	FakeOutputThread outputThread;
+	FakeRenderThread renderThread;
+
+	exchange.metrics.completedFrames = 10;
+	exchange.metrics.scheduledFrames = 10;
+	(void)telemetry.Sample(exchange, output, outputThread, renderThread);
+
+	std::this_thread::sleep_for(std::chrono::milliseconds(5));
+
+	exchange.metrics.completedFrames = 20;
+	exchange.metrics.scheduledFrames = 19;
+	const auto snapshot = telemetry.Sample(exchange, output, outputThread, renderThread);
+	Expect(snapshot.sampleSeconds > 0.0, "second telemetry sample has elapsed time");
+	Expect(snapshot.renderFps > 0.0, "render fps is computed from completed frame delta");
+	Expect(snapshot.scheduleFps > 0.0, "schedule fps is computed from scheduled frame delta");
+}
+
+void TestTelemetrySerializesToJson()
+{
+	RenderCadenceCompositor::CadenceTelemetrySnapshot snapshot;
+	snapshot.sampleSeconds = 1.0;
+	snapshot.renderFps = 59.94;
+	snapshot.scheduleFps = 60.0;
+	snapshot.freeFrames = 7;
+	snapshot.completedFrames = 1;
+	snapshot.scheduledFrames = 4;
+	snapshot.renderedTotal = 120;
+	snapshot.scheduledTotal = 118;
+	snapshot.completedPollMisses = 3;
+	snapshot.scheduleFailures = 0;
+	snapshot.completions = 117;
+	snapshot.displayedLate = 1;
+	snapshot.dropped = 2;
+	snapshot.shaderBuildsCommitted = 1;
+	snapshot.shaderBuildFailures = 0;
+	snapshot.deckLinkBufferedAvailable = true;
+	snapshot.deckLinkBuffered = 4;
+	snapshot.deckLinkScheduleCallMilliseconds = 1.25;
+
+	const std::string json = RenderCadenceCompositor::CadenceTelemetryToJson(snapshot);
+	const std::string expected =
+		"{\"sampleSeconds\":1,\"renderFps\":59.94,\"scheduleFps\":60,"
+		"\"free\":7,\"completed\":1,\"scheduled\":4,"
+		"\"renderedTotal\":120,\"scheduledTotal\":118,"
+		"\"completedPollMisses\":3,\"scheduleFailures\":0,"
+		"\"completions\":117,\"late\":1,\"dropped\":2,"
+		"\"shaderCommitted\":1,\"shaderFailures\":0,"
+		"\"deckLinkBufferedAvailable\":true,\"deckLinkBuffered\":4,"
+		"\"scheduleCallMs\":1.25}";
+	Expect(json == expected, "telemetry snapshot serializes to stable JSON");
+}
+
+void TestUnavailableDeckLinkBufferSerializesAsNull()
+{
+	RenderCadenceCompositor::CadenceTelemetrySnapshot snapshot;
+	snapshot.deckLinkBufferedAvailable = false;
+
+	const std::string json = RenderCadenceCompositor::CadenceTelemetryToJson(snapshot);
+	Expect(
+		json.find("\"deckLinkBufferedAvailable\":false,\"deckLinkBuffered\":null") != std::string::npos,
+		"unavailable DeckLink buffer depth serializes as null");
+}
+}
+
+int main()
+{
+	TestTelemetrySamplesCompletedPollMissesAndShaderCounts();
+	TestTelemetryComputesRatesFromDeltas();
+	TestTelemetrySerializesToJson();
+	TestUnavailableDeckLinkBufferSerializesAsNull();
+
+	if (gFailures != 0)
+	{
+		std::cerr << gFailures << " telemetry test failure(s).\n";
+		return 1;
+	}
+
+	std::cout << "RenderCadenceCompositor telemetry tests passed.\n";
+	return 0;
+}

ui/src/App.jsx

@@ -30,7 +30,7 @@ function App() {
   const [dropTargetLayerId, setDropTargetLayerId] = useState(null);
 
   const layers = appState?.layers ?? [];
-  const shaders = appState?.shaders ?? [];
+  const shaders = (appState?.shaders ?? []).filter((shader) => shader.available !== false);
   const performance = appState?.performance ?? {};
   const runtime = appState?.runtime ?? {};
   const video = appState?.video ?? {};