Docs update

src/README.md

@@ -78,6 +78,8 @@ Included now:
 - local HTTP control server matching the OpenAPI route surface
 - HTTP layer controls for add, remove, reorder, bypass, shader change, parameter update, and parameter reset
 - trigger parameters as latest-pulse controls with shader-visible count/time
+- startup restore from `runtime/runtime_state.json`
+- debounced background autosave for durable layer-stack UI/API changes
 - startup config provider for `config/runtime-host.json`
 - quiet telemetry health monitor
 - optional preview window fed from completed system-memory frames on its own thread
@@ -89,12 +91,10 @@ Intentionally not included yet:
 - additional input format conversion/scaling
 - temporal/history/feedback shader storage
 - texture/LUT asset upload
-- runtime state
+- manual stack preset save/load
 - OSC control
-- persistent control/state writes
 - trigger event history for stacked repeated pulses
 - screenshots
-- persistence
 
 Those features should be ported only after the cadence spine is stable.
 
@@ -143,8 +143,10 @@ This tracks parity with `apps/LoopThroughWithOpenGLCompositing`.
 - [x] CPU-side MSDF/MTSDF font atlas generation cache
 - [x] Single-line text parameter rasterization and GL binding
 - [ ] Trigger history/event buffers for overlapping repeated trigger effects
-- [ ] Full runtime state store/read model
-- [ ] Persistent layer stack/config writes
+- [x] Startup restore from latest runtime layer state
+- [x] Debounced background autosave for durable layer-stack changes
+- [ ] Manual stack preset save/load
+- [ ] Persistent config writes
 - [ ] OSC ingress
 - [x] Preview output from a non-consuming system-memory tap
 - [ ] Screenshot capture
@@ -195,9 +197,9 @@ Currently consumed fields:
 
 - `serverPort`
 - `shaderLibrary`
-- `oscBindAddress`
-- `oscPort`
-- `oscSmoothing`
+- `oscBindAddress` (reported for compatibility; OSC ingress is not wired yet)
+- `oscPort` (reported for compatibility; OSC ingress is not wired yet)
+- `oscSmoothing` (reported for compatibility; OSC ingress is not wired yet)
 - `inputVideoFormat`
 - `inputFrameRate`
 - `outputVideoFormat`
@@ -212,6 +214,8 @@ When `previewEnabled` is true, the preview window runs on `PreviewWindowThread`.
 
 The loaded config is treated as a read-only startup snapshot. Subsystems that need config should receive this snapshot or a narrowed config struct from app orchestration; they should not reload files independently.
 
+`autoReload` is exposed in config and state for compatibility, but automatic file watching is not currently wired. Use `POST /api/reload` or the control UI reload button to rescan shader files and manifests.
+
 Supported CLI overrides:
 
 - `--shader <shader-id>`
@@ -236,9 +240,10 @@ Current endpoints:
 - `GET /docs/openapi.yaml` and `GET /openapi.yaml`: serves the OpenAPI document
 - `GET /docs`: serves Swagger UI
 - `POST /api/layers/add`, `/remove`, `/reorder`, `/set-bypass`, `/set-shader`, `/update-parameter`, and `/reset-parameters` use the shared runtime control-command path
+- `POST /api/reload`: rescans the shader library, refreshes manifests, and queues recompilation for every catalog-valid layer in the active stack
 - other OpenAPI POST routes are present but return `{ "ok": false, "error": "Endpoint is not implemented in RenderCadenceCompositor yet." }`
 
-The HTTP server runs on its own thread. It serves static UI/docs files, samples/copies telemetry through callbacks, and translates POST bodies into runtime control commands. Command execution is app-owned, so future OSC ingress can create the same commands without depending on HTTP route code. Control commands may update the display layer model, start background shader builds, or publish an already-built render-layer snapshot, but they do not call render work or DeckLink scheduling directly.
+The HTTP server runs on its own thread. It serves static UI/docs files, samples/copies telemetry through callbacks, and translates POST bodies into runtime control commands. Command execution is app-owned, so future OSC ingress can create the same commands without depending on HTTP route code. Control commands may update the display layer model, request debounced runtime-state persistence, start background shader builds, or publish an already-built render-layer snapshot, but they do not call render work or DeckLink scheduling directly.
 
 ## Optional DeckLink Output
 
@@ -332,17 +337,19 @@ Healthy first-run signs:
 - `deckLinkScheduleRealignments` does not increase continuously
 - `late` and `dropped` do not increase continuously
 - `scheduleFailures` does not increase
-- `shaderCommitted` becomes `1` after the background Happy Accident compile completes
+- `shaderCommitted` increases after the restored/default runtime layer compiles and commits
 - `shaderFailures` remains `0`
 
 `completedPollMisses` means the DeckLink scheduling thread woke up before a completed frame was available. It is not a DeckLink playout underrun by itself. Treat it as healthy polling noise when `scheduled`, `decklinkBuffered`, `late`, `dropped`, and `scheduleFailures` remain stable.
 
-## Runtime Slang Shader Test
+## Runtime Slang Shader Stack
 
-On startup the app begins compiling the selected shader package on a background thread owned by the app orchestration layer. The default is `shaders/happy-accident`.
+On startup the app first tries to restore `runtime/runtime_state.json`. Valid saved layers are rebuilt in saved order, including shader id, bypass state, and parameter values. Missing shader packages are skipped, invalid saved parameter values fall back to manifest defaults, and if the runtime-state file is missing or unusable the app falls back to the configured shader package. The default configured shader is `shaders/happy-accident`.
 
 The render thread keeps drawing the simple motion renderer while Slang compiles. It does not choose packages, launch Slang, or track build lifecycle. Once a completed shader artifact is published, the render-thread-owned runtime scene queues changed layers to a shared-context GL prepare worker. That worker compiles/links runtime shader programs off the cadence thread. The render thread only swaps in an already-prepared GL program at a frame boundary. If either the Slang build or GL preparation fails, the app keeps rendering the current renderer or simple motion fallback.
 
+`POST /api/reload` rescans `shaders/`, re-reads manifests, refreshes supported shader metadata, reconciles active layer parameters against changed definitions, and queues recompilation for every catalog-valid layer in the active stack. It does not compile every package in the shader library; packages are compiled when they are part of the active stack.
+
 Current runtime shader support is deliberately limited to stateless full-frame packages:
 
 - one or more named passes
@@ -371,7 +378,7 @@ Shader source semantics:
 
 The `/api/state` shader list uses the same support rules as runtime shader compilation and reports only packages this app can run today. Unsupported manifest feature sets such as temporal, feedback, and texture-backed shaders are hidden from the control UI for now.
 
-Runtime shaders are exposed through `RuntimeLayerModel` as display layers with manifest parameter definitions, current parameter values, build status, and render-ready artifacts. POST controls mutate this app-owned model and may start background shader builds when the selected shader changes.
+Runtime shaders are exposed through `RuntimeLayerModel` as display layers with manifest parameter definitions, current parameter values, build status, and render-ready artifacts. POST controls mutate this app-owned model and may start background shader builds when the selected shader changes or when `/api/reload` is requested. Durable UI/API layer changes request a debounced background write to `runtime/runtime_state.json`. OSC ingress is not wired yet; when it is added, OSC-driven changes should stay out of autosave unless an explicit persistence policy is introduced.
 
 When a layer becomes render-ready, the app publishes the ready render-layer snapshot to the render thread. The render thread owns the GL-side `RuntimeRenderScene`, diffs that snapshot at a frame boundary, queues new or changed pass programs to the shared-context prepare worker, swaps in a full prepared render plan only after every pass is ready, removes obsolete GL programs, and renders ready layers in order. Stacked stateless full-frame shaders render through internal ping-pong targets so each layer can sample the previous layer through `gLayerInput`; multipass shaders route named intermediate outputs through their manifest-declared pass inputs, and the final ready layer renders to the output target.
 
@@ -429,7 +436,7 @@ This app keeps the same core behavior but splits it into modules that can grow:
 - `render/readback/`: PBO-backed BGRA8 readback and completed-frame publication
 - `render/runtime/RuntimeRenderScene`: render-thread-owned GL scene for ready runtime shader layers
 - `render/runtime/RuntimeShaderPrepareWorker`: shared-context runtime shader program compile/link worker
-- `runtime/`: app-owned shader layer readiness model, runtime Slang build bridge, and completed artifact handoff
+- `runtime/`: app-owned shader layer readiness model, runtime Slang build bridge, runtime-state persistence, and completed artifact handoff
 - `control/`: control action results and runtime-state JSON presentation
 - `control/http/`: local HTTP API, static UI serving, OpenAPI serving, and WebSocket updates
 - `json/`: compact JSON serialization helpers
@@ -445,7 +452,6 @@ Only after this app matches the probe's smooth output:
 
 1. replace `SimpleMotionRenderer` with a render-scene interface
 2. port shader package rendering
-3. port runtime snapshots/live state
-4. add control services
-5. add preview/screenshot from system-memory frames
-6. add scaling and additional input format support after the BGRA8/raw-UYVY8 input edge is stable
+3. broaden runtime snapshots/live state toward OSC and presets
+4. add screenshot capture from system-memory frames
+5. add scaling and additional input format support after the BGRA8/raw-UYVY8 input edge is stable