clean split

docs/FORKING_RENDER_CADENCE_BASE.md

@@ -6,7 +6,9 @@ This note captures the fork-readiness review for using this repository as a base
 
 The repository is clean enough for an internal fork, but it needs a small hygiene pass before it becomes a comfortable long-lived base repo.
 
-The important architecture is already in place: render cadence, video input/output, frame exchange, readback, preview, control, and shader build work are mostly separated by role. The main replacement point is the render-content adapter in `src/render/RuntimeShaderRenderContent.*`, where the current shader-package renderer decides what to draw into the framebuffer handed to it by `RenderThread`.
+The important architecture is already in place: render cadence, video input/output, frame exchange, readback, preview, control, and shader build work are mostly separated by role. The app-side replacement point is now `IRuntimeContentController` in `src/app/RuntimeContentController.h`. The current shader package stack is plugged in by `ShaderRuntimeContentController`, while a fork can provide a D3D-engine controller without making the host app own Slang, shader catalogs, or shader layer state.
+
+The current render-thread implementation still uses OpenGL for its context and readback path. If the fork's renderer is truly D3D rather than GL content, keep the app/video/frame-exchange boundary and replace the render-thread/content implementation that publishes completed system-memory frames.
 
 For a new repo, keep the cadence and frame handoff machinery, then replace or narrow the runtime shader rendering layer.
 
@@ -23,6 +25,7 @@ These parts are the useful base for the fork:
 - `src/app`: startup, config, video backend factory, runtime layer orchestration, preview, telemetry, and HTTP server hookup.
 - `src/control/http`, `src/control/osc`, `src/telemetry`, `src/logging`, and `ui`: useful if the new repo still wants a local control surface. `control/osc` is currently a status/lifecycle stub, not a UDP listener.
 - `src/app/RenderCadenceHttpRoutes.*`: useful only if the new repo keeps this app's current `/api/...` control surface.
+- `src/app/RuntimeContentController.h`: the app-side runtime-content boundary. Keep the interface shape and provide a fork-owned implementation for D3D engine control/state.
 
 ## Replace Or Rework
 
@@ -31,6 +34,7 @@ These are most likely to change when the fork renders something other than shade
 - `src/render/runtime`: current runtime shader scene, renderer, text texture cache, and shared-context shader preparation.
 - `src/runtime/shader`: background Slang package build bridge.
 - `src/shader`: shader package manifest parsing and Slang wrapper generation, unless the new renderer keeps the same shader package contract.
+- `src/app/ShaderRuntimeContentController.*`: current Slang shader-stack implementation of the app runtime-content boundary.
 - `shaders/`: bundled shader package library.
 - `runtime/templates/shader_wrapper.slang.in`: only needed for the current Slang package pipeline.
 - `src/app/RenderCadenceHttpRoutes.*`: replace this with a fork-owned route module if the new renderer has different controls, while keeping `src/control/http/HttpControlServer.*` as the socket/static/WebSocket shell.
@@ -38,6 +42,8 @@ These are most likely to change when the fork renders something other than shade
 
 The first fork step is now in place: `RenderThread` preserves the cadence/readback shell and calls a narrow render-content interface behind the draw call. A new repo can swap that implementation without touching video I/O scheduling.
 
+The shader stack is also separated from `RenderCadenceApp` now. The app owns only an `IRuntimeContentController`; `RenderCadenceCompositor.cpp` wires the current `ShaderRuntimeContentController` into that slot. A D3D fork should wire a D3D runtime-content controller there and then replace the render-thread content/readback implementation as needed.
+
 The HTTP control boundary is also split now. `HttpControlServer` owns transport, static-file helpers, OpenAPI helper serving, and WebSocket state transport; `RenderCadenceHttpRoutes` owns this app's REST endpoint map. A fork that wants the same browser/server plumbing can provide its own route callback and leave the Render Cadence-specific endpoints behind.
 
 ## Current Swap Point
@@ -68,17 +74,18 @@ Before cutting a long-lived fork, fix or decide these items:
 - Keep `runtimeShaderId` empty in checked-in config unless this repo intentionally wants a default startup shader again.
 - Keep runtime third-party discovery aligned with CMake. Font atlas generation and Slang compilation now both check explicit tool roots, `THIRD_PARTY_ROOT`, the private `video-io-3rdParty` bundle, and legacy or packaged `3rdParty` layouts.
 - Make `config/runtime-host.json` portable. Current checked-in defaults include a local NDI source name and DeckLink output.
-- Decide whether the fork keeps the Slang shader package contract. If not, retire or clearly isolate `shaders/SHADER_CONTRACT.md`, shader package UI, and shader manifest tests.
+- Decide whether the fork keeps the Slang shader package contract. If not, replace `ShaderRuntimeContentController`, retire or clearly isolate `shaders/SHADER_CONTRACT.md`, shader package UI, and shader manifest tests.
+- For a D3D engine fork, decide whether to bridge D3D output into the existing GL/readback path temporarily or replace `RenderThread`/readback with a D3D-native publisher that still writes completed `SystemFrameExchange` frames.
 - Mark older docs that reference `apps/LoopThroughWithOpenGLCompositing` as historical, or update them to point at the current `src/` implementation.
 - Keep `runtime/` generated output ignored, and keep only `runtime/templates/` plus `runtime/README.md` tracked.
 - Keep the private SDK bundle as a submodule only if the new repo is intended for the same org/build environment. External forks should use ignored `3rdParty/` or explicit CMake SDK paths.
 
 ## Verification Snapshot
 
-Last checked locally on 2026-05-30 after the Slang lookup alignment:
+Last checked locally on 2026-05-30 after the runtime-content controller split:
 
 - UI production build passed with `npm.cmd run build`.
-- Native debug build passed for `RenderCadenceCompositor`, `ShaderSlangValidationTests`, and `ShaderCompilerLookupTests`.
+- Native debug build passed for `RenderCadenceCompositor`.
 - Native tests passed 26 of 26 with `ctest --test-dir build\vs2022-x64-debug -C Debug --output-on-failure`.
 - `FontAtlasBuilderTests` now passes with `msdf-atlas-gen.exe` supplied by the private `video-io-3rdParty/msdf-atlas-gen` bundle.
 - `ShaderCompilerLookupTests` covers `SLANG_ROOT`, `THIRD_PARTY_ROOT`, repo `video-io-3rdParty`, legacy `3rdParty`, and packaged `3rdParty/slang` Slang layouts.
@@ -88,9 +95,9 @@ The generated Visual Studio `RUN_TESTS` target did not build missing test execut
 ## Recommended Fork Sequence
 
 1. Make the hygiene fixes above in this repo or immediately after the fork.
-2. Keep `IRenderContent` as the boundary behind the `RenderThread` draw call.
-3. Keep `RuntimeShaderRenderContent` as the baseline implementation until the fork's renderer exists.
-4. Add the new renderer beside it or replace the default adapter.
+2. Keep `IRuntimeContentController` as the app-side boundary and replace `ShaderRuntimeContentController` with the fork's D3D engine control/state implementation.
+3. Keep `IRenderContent` as the render-thread draw-call boundary only if the fork remains GL-backed or uses a GL/D3D bridge.
+4. If the fork is D3D-native, replace the render-thread/readback implementation while preserving completed-frame publication into `SystemFrameExchange`.
 5. Verify that video output still consumes completed frames and never requests rendering directly.
 6. Only then remove shader package pieces that the new repo no longer needs.