aiden/video-shader-toys
1
0
Fork 1
Code Issues Pull Requests Actions Releases 5 Wiki Activity

GROUND WORK PHASE 3
All checks were successful
CI / React UI Build (push) Successful in 11s
Details
CI / Native Windows Build And Tests (push) Successful in 2m32s
Details
CI / Windows Release Package (push) Successful in 2m34s
Details

Browse Source
This commit is contained in:
Aiden
2026-05-11 16:32:51 +10:00
parent 00b6ad4c36
commit 0808171677
9 changed files with 582 additions and 246 deletions
Download Patch File Download Diff File Expand all files Collapse all files

28
docs/PHASE_3_LIVE_STATE_SERVICE_COORDINATION_DESIGN.md
View File

@@ -7,7 +7,7 @@ Phase 1 split runtime responsibilities into named subsystems. Phase 2 added the
## Status
- Phase 3 design package: proposed.
- Phase 3 implementation: not started.
- Phase 3 implementation: groundwork started.
- Current alignment: the repo has the right building blocks, but `OpenGLComposite::renderEffect()` still manually reconciles transient OSC overlays, completed OSC commits, committed/live snapshot selection, and render-state resolution on the render path.
Current footholds:
@@ -15,7 +15,9 @@ Current footholds:
- `RuntimeStore` is split into durable state collaborators: `RuntimeConfigStore`, `LayerStackStore`, `ShaderPackageCatalog`, `RenderSnapshotBuilder`, presentation read models, and `HealthTelemetry`.
- `RuntimeCoordinator` owns mutation validation/classification and publishes accepted/rejected/follow-up events.
- `RuntimeSnapshotProvider` publishes render snapshots from `RenderSnapshotBuilder`.
- `RenderEngine` owns render-local OSC overlay state and final render-layer resolution.
- `RuntimeLiveState` owns transient OSC overlay bookkeeping and commit-settlement policy.
- `RenderStateComposer` exists as the first pure composition boundary for combining base layer state with live overlays.
- `RenderEngine` still owns final render-layer resolution, but its OSC overlay bookkeeping now delegates to `RuntimeLiveState`.
- `ControlServices` owns OSC ingress, pending OSC updates, completed OSC commit notifications, and service start/stop.
- `RuntimeEventDispatcher` now routes accepted mutations, reloads, snapshots, shader build events, backend observations, and health observations.
@@ -250,6 +252,8 @@ Introduce `RuntimeLiveState`, `RenderStateComposer`, or an equivalent pair of cl
Start by moving pure data operations out of `RenderEngine::ResolveRenderLayerStates(...)` without changing behavior.
Status: started. `runtime/live/RuntimeLiveState` and `runtime/live/RenderStateComposer` now exist, are included in the build, and have a focused `RuntimeLiveStateTests` target.
### Step 2. Move OSC Overlay Bookkeeping Behind The Boundary
Move these responsibilities out of the current frame orchestration:
@@ -261,6 +265,8 @@ Move these responsibilities out of the current frame orchestration:
The first implementation can still be called synchronously from the current render path. The important part is that the behavior has a named owner and tests.
Status: started. `RenderEngine` still exposes the compatibility methods used by `OpenGLComposite`, but it now delegates overlay updates, commit completions, smoothing, generation matching, and commit-request creation to `RuntimeLiveState`.
### Step 3. Bridge Service Queues To Events Or Live-State Commands
Replace `OpenGLComposite::renderEffect()` queue draining with a bridge that publishes or applies:
@@ -324,14 +330,26 @@ Existing useful homes:
- `RuntimeSubsystemTests` for pure state/composer behavior
- `RuntimeEventTypeTests` for event bridge behavior
- a new `RuntimeLiveStateTests.cpp` target if the live-state code grows enough
- `RuntimeLiveStateTests` for the new live-state/composer boundary
## Parallel Work Lanes
The current groundwork is intended to let these lanes proceed in parallel with low overlap:
| Lane | Primary files | Goal |
| --- | --- | --- |
| A. Live-state behavior | `runtime/live/RuntimeLiveState.*`, `tests/RuntimeLiveStateTests.cpp` | Finish stale completion tests, smoothing edge cases, trigger behavior, and overlay settle policy. |
| B. Render-state composition | `runtime/live/RenderStateComposer.*`, `gl/RenderEngine.*` | Move more of `RenderEngine::ResolveRenderLayerStates(...)` value composition behind the pure composer while keeping GL calls in `RenderEngine`. |
| C. Service bridge | `control/RuntimeServices.*`, `control/ControlServices.*`, possible new bridge class | Stop `OpenGLComposite::renderEffect()` from draining OSC update/completion queues directly. |
| D. App-frame orchestration | `gl/OpenGLComposite.*`, `gl/RuntimeUpdateController.*` | Replace render-effect glue with a narrow frame-state preparation call and commit-request handoff. |
| E. Persistence boundary | `runtime/coordination/RuntimeCoordinator.*`, `runtime/store/*`, event tests | Keep persistence request publication explicit and prepare for a later background writer without changing storage behavior yet. |
## Phase 3 Exit Criteria
Phase 3 can be considered complete once the project can say:
- [ ] final render-state composition has a named, testable owner outside `OpenGLComposite`
- [ ] transient OSC overlay state has a named owner and tests
- [ ] final render-state composition has a named, testable owner outside `OpenGLComposite` (groundwork exists via `RenderStateComposer`; full snapshot/cache resolution still needs to move behind it)
- [x] transient OSC overlay state has a named owner and tests
- [ ] overlay commit requests and completions no longer require `OpenGLComposite` to drain service queues directly
- [ ] `RenderEngine` is closer to GL/render resource ownership and less responsible for value composition
- [ ] `RuntimeStore` remains durable-state focused and does not gain live overlay responsibilities