Font fix and forkable docs

docs/FORKING_RENDER_CADENCE_BASE.md

@@ -0,0 +1,93 @@
+# Forking The Render Cadence Base
+
+This note captures the fork-readiness review for using this repository as a base where the render cadence and video I/O work are kept, but the GPU content being rendered is replaced in a separate repository.
+
+## Verdict
+
+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-thread draw path in `src/render/thread/RenderThread.cpp`, where cadence, input upload, readback, and frame publication wrap the actual GPU rendering call.
+
+For a new repo, keep the cadence and frame handoff machinery, then replace or narrow the runtime shader rendering layer.
+
+## Keep
+
+These parts are the useful base for the fork:
+
+- `src/frames`: CPU frame handoff, input mailbox, and completed-frame exchange.
+- `src/video/core`: backend-neutral input/output contracts.
+- `src/video/decklink`, `src/video/ndi`, and `src/video/playout`: concrete video I/O edges and scheduling support.
+- `src/render/thread`: render cadence ownership, readback pumping, runtime render-layer commit point, and metrics.
+- `src/render/readback`: BGRA8 PBO readback and completed-frame publication.
+- `src/platform`: hidden GL window/context support.
+- `src/app`: startup, config, video backend factory, runtime layer orchestration, preview, telemetry, and HTTP server hookup.
+- `src/control`, `src/telemetry`, `src/logging`, and `ui`: useful if the new repo still wants a local control surface.
+
+## Replace Or Rework
+
+These are most likely to change when the fork renders something other than shader packages:
+
+- `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.
+- `shaders/`: bundled shader package library.
+- `runtime/templates/shader_wrapper.slang.in`: only needed for the current Slang package pipeline.
+- Shader-specific UI affordances in `ui`, if the new renderer has a different control model.
+
+The cleanest first fork step is to preserve `RenderThread`'s cadence/readback shell and introduce a narrow render-content interface behind the draw call. Then the new repo can swap the implementation without touching video I/O scheduling.
+
+## Current Swap Point
+
+The current draw decision happens inside the readback queue call in `src/render/thread/RenderThread.cpp`:
+
+```cpp
+if (runtimeRenderScene.HasLayers())
+	runtimeRenderScene.RenderFrame(index, mConfig.width, mConfig.height, videoInputTexture);
+else if (videoInputTexture != 0)
+	renderer.RenderTexture(videoInputTexture);
+else
+	renderer.RenderFrame(index);
+```
+
+That is the practical boundary for a fork:
+
+- keep the tick clock, input upload, readback queueing, and `SystemFrameExchange` publication around it
+- replace what draws into the current GL framebuffer
+- keep video output consuming already completed system-memory frames
+
+Do not move DeckLink, NDI, file I/O, shader compilation, or control handling into the cadence path while doing the replacement.
+
+## Fork Hygiene Checklist
+
+Before cutting a long-lived fork, fix or decide these items:
+
+- Remove hardcoded `happy-accident` assumptions in `src/app/AppConfig.h` and `src/runtime/shader/RuntimeSlangShaderCompiler.cpp`.
+- Align remaining runtime third-party discovery with CMake. Font atlas generation now checks `MSDF_ATLAS_GEN_ROOT`, `THIRD_PARTY_ROOT`, `3rdParty`, and `video-io-3rdParty`; shader compiler lookup still needs the same treatment for Slang.
+- 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.
+- 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 font-builder lookup fix:
+
+- Worktree was clean before documentation changes.
+- UI production build passed with `npm.cmd run build`.
+- Native debug build passed with `cmake --build --preset build-debug --parallel`.
+- Native tests passed 24 of 24 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.
+
+The generated Visual Studio `RUN_TESTS` target did not build missing test executables by itself during the first local run; building the debug preset first produced the test binaries.
+
+## Recommended Fork Sequence
+
+1. Make the hygiene fixes above in this repo or immediately after the fork.
+2. Add a small render-content abstraction behind the `RenderThread` draw call.
+3. Port the existing runtime shader renderer behind that abstraction as the baseline implementation.
+4. Add the new renderer beside it.
+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.
+
+That sequence preserves the hard-won cadence/video I/O behavior while giving the fork a clean place to become its own renderer.