Doc cleanup

docs/CURRENT_SYSTEM_ARCHITECTURE.md

@@ -11,8 +11,8 @@ The app is a native C++ OpenGL compositor with:
 - optional DeckLink input
 - optional DeckLink scheduled output
 - a render-thread-owned OpenGL context
-- runtime Slang shader packages from `shaders/`
-- a configurable active layer stack
+- a pluggable app-side runtime-content controller
+- the default runtime Slang shader package stack from `shaders/`
 - a local HTTP/WebSocket control server
 - optional Win32/GDI preview from system-memory output frames
 - background runtime-state persistence
@@ -20,7 +20,7 @@ The app is a native C++ OpenGL compositor with:
 
 Primary source areas:
 
-- `src/app`: startup/shutdown orchestration, config loading, runtime layer controller
+- `src/app`: startup/shutdown orchestration, config loading, video backend factory, runtime-content controller boundary, and the default shader runtime-content controller
 - `src/render`: cadence clock, input texture upload, render-content boundary, readback, and runtime GL support
 - `src/render/thread`: render thread lifecycle, cadence loop, metrics, and runtime shader commit mailbox
 - `src/render/runtime`: render-thread-owned runtime shader scene, renderer, text texture upload cache, and shared-context shader prepare worker
@@ -44,18 +44,20 @@ Primary source areas:
 Startup broadly proceeds as:
 
 1. Load `config/runtime-host.json` through `AppConfigProvider`, then apply CLI overrides.
-2. Load the supported shader catalog from the configured `shaderLibrary`.
-3. Start the runtime-state persistence writer.
-4. Try to restore `runtime/runtime_state.json`.
-5. If restore fails or no usable state exists, create one layer from the configured default shader.
-6. Start the render thread.
-7. Queue background Slang builds for every pending active layer.
-8. Build a small completed-frame reserve.
-9. Start optional preview, optional video output, telemetry, and HTTP control.
+2. Initialize the active `IRuntimeContentController`. The checked-in app uses `ShaderRuntimeContentController`, which loads the supported shader catalog, starts runtime-state persistence, and tries to restore `runtime/runtime_state.json`.
+3. If restore fails or no usable state exists, the shader controller falls back to the optional configured startup shader. The checked-in config leaves `runtimeShaderId` empty, so a fresh host keeps the simple fallback renderer.
+4. Start the render thread.
+5. Start the active runtime-content controller. The shader controller queues background Slang builds for every pending active layer.
+6. Build a small completed-frame reserve.
+7. Start optional preview, optional video output, telemetry, and HTTP control.
 
 The runtime-state restore is intentionally app/control side work. The render thread does not read JSON, inspect the shader library, or decide what to compile.
 
-## Runtime Layer State
+## Runtime Content And Shader Layer State
+
+`RenderCadenceApp` owns startup, video output, preview, telemetry, OSC status, and HTTP server lifetime. It does not own the Slang shader stack directly. Runtime content plugs in through `IRuntimeContentController`.
+
+The checked-in implementation is `ShaderRuntimeContentController`. It wraps `RuntimeLayerController`, exposes shader catalog/layer JSON for `/api/state`, handles shader layer POST commands, and publishes render-ready shader layer snapshots to the render thread.
 
 `RuntimeLayerController` owns the app-side layer model and coordinates:
 
@@ -78,7 +80,7 @@ The runtime-state restore is intentionally app/control side work. The render thr
 - current parameter values
 - render-ready artifacts
 
-The current durable runtime state is stored in `runtime/runtime_state.json`. It contains the active stack order, shader ids, bypass flags, and parameter values. On startup, valid saved layers are restored in order. Missing shader packages are skipped, invalid saved parameter values fall back to manifest defaults, and a missing or unusable file falls back to the configured default shader.
+The current durable runtime state is stored in `runtime/runtime_state.json`. It contains the active stack order, shader ids, bypass flags, and parameter values. On startup, valid saved layers are restored in order. Missing shader packages are skipped, invalid saved parameter values fall back to manifest defaults, and a missing or unusable file falls back to the optional configured startup shader.
 
 Manual stack preset routes are present in the UI/OpenAPI surface but are not implemented in the current native command path yet. `runtime_state.json` is the supported latest-working-state mechanism.
 
@@ -132,7 +134,7 @@ The render path consumes published render-layer snapshots. It does not:
 - handle HTTP or OSC
 - call DeckLink discovery/setup APIs
 
-When a runtime shader build completes, the app publishes a render-layer artifact. The render thread forwards pending layer snapshots to the active render-content adapter. The default `RuntimeShaderRenderContent` owns the runtime scene, diffs the snapshot, and queues changed pass programs to the shared-context prepare worker. The render thread swaps in an already-prepared render plan at a frame boundary through that adapter.
+When a runtime shader build completes, the default shader runtime-content controller publishes a render-layer artifact. The render thread forwards pending layer snapshots to the active render-content adapter. The default `RuntimeShaderRenderContent` owns the runtime scene, diffs the snapshot, and queues changed pass programs to the shared-context prepare worker. The render thread swaps in an already-prepared render plan at a frame boundary through that adapter.
 
 ## Video And Preview
 
@@ -156,7 +158,7 @@ The HTTP server runs on its own thread. `HttpControlServer` owns socket lifetime
 - OpenAPI/Swagger docs
 - `GET /api/state`
 - `/ws` state updates
-- layer mutation POST routes
+- layer mutation POST routes, dispatched to the active runtime-content controller
 - `/api/reload`
 
 Known but not implemented in the current native command path: