Docs update

README.md

@@ -17,11 +17,13 @@ The app loads shader packages from `shaders/`, compiles Slang to GLSL at runtime
 
 Native app internals are grouped by boundary:
 
-- `videoio/`: backend-neutral video I/O contracts, formats, and playout timing.
-- `videoio/decklink/`: DeckLink-specific device adapter, callbacks, and SDK bindings.
-- `gl/renderer/`: low-level OpenGL resources and extension helpers.
-- `gl/pipeline/`: frame pipeline, render passes, video I/O bridge, preview/readback, and screenshots.
-- `gl/shader/`: shader compilation, texture/text assets, UBO packing, and shader program ownership.
+- `app/`: startup/shutdown orchestration and runtime layer controller.
+- `control/`: HTTP/WebSocket server, command parsing, and runtime-state JSON presentation.
+- `frames/`: system-memory frame exchange and input mailbox handoff.
+- `render/`: render thread, readback, runtime render scene, and shared-context shader program preparation.
+- `runtime/`: shader catalog support, layer model, Slang build bridge, font atlas build, and runtime-state persistence.
+- `shader/`: shader package parsing and Slang compilation helpers.
+- `video/`: DeckLink input/output edges, format helpers, and scheduling.
 
 ## Requirements
 
@@ -72,10 +74,8 @@ The native app serves `ui/dist` when it exists, otherwise it falls back to the s
 The control UI provides:
 
 - A searchable shader library for adding layers.
-- Compact parameter rows with inline descriptions and OSC copy controls.
-- Stack save/recall presets.
+- Compact parameter rows with inline descriptions and intended OSC route copy controls.
 - Manual shader reload.
-- Screenshot capture from the final output render target.
 
 ## Package
 
@@ -138,7 +138,6 @@ Current native test coverage includes:
 - Parameter normalization and preset filename safety.
 - Shader manifest parsing, temporal manifest validation, and package registry scanning.
 - Video I/O format helpers, v210/Ay10 row-byte math, v210 pack/unpack math, playout scheduler timing, and fake backend contract coverage.
-- OSC packet parsing.
 - Slang validation for every available shader package.
 
 ## Runtime Configuration
@@ -172,11 +171,13 @@ The control UI is available at:
 http://127.0.0.1:<serverPort>
 ```
 
-## Runtime State And Presets
+## Runtime State
 
-The current layer stack is autosaved to `runtime/runtime_state.json` whenever layers, shader assignments, bypass state, ordering, or parameter values change. On startup, the host reloads that file before compiling the stack, so the last working stack should come back automatically.
+The current layer stack is autosaved to `runtime/runtime_state.json` whenever durable UI/API layer changes are accepted: add/remove, shader assignment, bypass state, ordering, parameter updates, parameter reset, and reload compatibility refreshes. Saves are debounced and written on a background worker, with a final flush during shutdown.
 
-Manual stack presets are still available from the control UI and are saved under `runtime/stack_presets/*.json`. Presets are useful for named looks, while `runtime_state.json` is the latest working state for the local machine.
+On startup, the host tries to reload `runtime/runtime_state.json` before compiling the stack. Valid saved layers are rebuilt in saved order, with shader id, bypass state, and parameter values restored. Missing shader packages are skipped, invalid saved parameter values fall back to shader defaults, and if the file is missing or unusable the app falls back to the configured default shader.
+
+Manual stack preset and screenshot routes are still present in the UI/OpenAPI surface, but they are not implemented by the current native command path yet. `runtime_state.json` is the supported latest-working-state mechanism for now.
 
 ## Control API
 
@@ -199,13 +200,15 @@ A Swagger UI page is available at:
 http://127.0.0.1:<serverPort>/docs
 ```
 
-Use those docs to inspect the `/api/state`, layer control, stack preset, and reload endpoints. Live state updates are also sent over the `/ws` WebSocket.
+Use those docs to inspect the `/api/state`, layer control, and reload endpoints. Live state updates are also sent over the `/ws` WebSocket.
 
-The control UI has a **Reload shaders** button. It rescans `shaders/`, re-reads manifests, queues shader compilation, refreshes shader availability/errors, and keeps the previous working shader stack running if a changed shader fails to compile.
+The control UI has a **Reload shaders** button. It rescans `shaders/`, re-reads manifests, refreshes shader availability/errors, updates active layer parameter definitions from changed manifests, and queues recompilation for every catalog-valid layer in the active stack. Missing shader packages are marked failed, and the previous working render stack remains active where possible until replacement builds commit successfully.
 
-Each parameter row also includes a small **OSC** button. Clicking it copies that parameter's OSC route to the clipboard.
+Each parameter row still exposes the intended OSC route in the UI, but OSC ingress is not wired in the current native host.
 
-The control UI also has a **Screenshot** button. It queues a capture of the final output render target and writes a PNG under:
+The control UI currently still shows preset and screenshot controls from the intended route surface. Those endpoints return an unimplemented action result in the native host until their backend paths are wired.
+
+The planned screenshot output directory is:
 
 ```text
 runtime/screenshots/
@@ -213,13 +216,15 @@ runtime/screenshots/
 
 ## OSC Control
 
-The native host also listens for OSC parameter control on the configured `oscBindAddress` and `oscPort`:
+OSC fields are present in `config/runtime-host.json` and `/api/state` for compatibility with the intended control surface, but the current native host does not start an OSC listener yet.
+
+The intended route shape is:
 
 ```text
 /VideoShaderToys/{LayerNameOrID}/{ParameterNameOrID}
 ```
 
-For example, `/VideoShaderToys/VHS/intensity` updates the `intensity` parameter on the first matching `VHS` layer. The listener accepts float, integer, string, and boolean OSC values, and validates them through the same shader parameter path as the REST API. OSC updates are coalesced and applied once per render tick, UI state broadcasts are throttled, and OSC-driven parameter changes are not autosaved to `runtime/runtime_state.json`. `oscSmoothing` adds a small per-frame easing amount for numeric OSC controls such as floats, `vec2`, and `color`, while booleans, enums, text, and triggers stay immediate. The default bind address is `127.0.0.1`; set `oscBindAddress` to `0.0.0.0` to accept OSC on all IPv4 interfaces. See `docs/OSC_CONTROL.md` for details.
+For now, use the REST layer parameter endpoints or the control UI for live parameter changes. Future OSC-driven parameter changes should stay out of autosave unless an explicit persistence policy is added.
 
 ## Shader Packages
 
@@ -243,8 +248,8 @@ Runtime-generated files are intentionally ignored:
 - `runtime/shader_cache/active_shader.raw.frag`
 - `runtime/shader_cache/active_shader.frag`
 - `runtime/runtime_state.json` autosaved latest stack and parameter state.
-- `runtime/stack_presets/*.json`
-- `runtime/screenshots/*.png` screenshots captured from the final output render target.
+- `runtime/stack_presets/*.json` planned manual preset output; preset routes are not implemented in the native host yet.
+- `runtime/screenshots/*.png` planned screenshot output; screenshot capture is not implemented in the native host yet.
 
 Only `runtime/templates/` and `runtime/README.md` are tracked.