added optional web component UI control

README.md

@@ -13,7 +13,8 @@ The app loads shader packages from `shaders/`, compiles Slang to GLSL at runtime
 - `runtime/templates/`: tracked shader wrapper templates.
 - `runtime/`: ignored generated runtime cache/state output. See `runtime/README.md`.
 - `tests/`: focused native tests for pure runtime logic.
-- `docs/FORKING_RENDER_CADENCE_BASE.md`: notes for forking the cadence/video I/O base while replacing the GPU-rendered content.
+- `docs/CURRENT_SYSTEM_ARCHITECTURE.md`: current architecture notes for the cadence/video I/O host.
+- `docs/RENDER_CADENCE_GOLDEN_RULES.md`: guardrails for changes that touch render cadence, runtime work, and video I/O.
 - `.gitea/workflows/ci.yml`: Gitea Actions CI for Windows native tests and Ubuntu UI build.
 
 Native app internals are grouped by boundary:
@@ -128,6 +129,7 @@ The control UI provides:
 
 - A searchable shader library for adding layers.
 - Compact parameter rows with inline descriptions and intended OSC route copy controls.
+- Shader-declared custom Web Component control panels with default-control fallback.
 - Manual shader reload.
 - Host config editing, save, restart request, and NDI input source discovery.
 - Compact video I/O and render cadence status.
@@ -313,7 +315,19 @@ shaders/<id>/
   optional-font-or-texture-assets
 ```
 
-See `SHADER_CONTRACT.md` for the manifest schema, parameter types, texture assets, font/text assets, temporal history support, optional render-pass declarations, and the Slang entry point contract. `shaders/text-overlay/` is the reference live text package and bundles Roboto Regular with its OFL license. Broken shader packages are shown as unavailable in the selector with their error text instead of preventing the app from launching.
+See `SHADER_CONTRACT.md` for the manifest schema, parameter types, texture assets, font/text assets, temporal history support, optional render-pass declarations, optional custom UI metadata, and the Slang entry point contract. `shaders/text-overlay/` is the reference live text package and bundles Roboto Regular with its OFL license. Broken shader packages are shown as unavailable in the selector with their error text instead of preventing the app from launching.
+
+Shader packages can optionally declare a custom control panel:
+
+```json
+"ui": {
+  "type": "webComponent",
+  "entry": "ui/controls.js",
+  "tag": "my-shader-controls"
+}
+```
+
+The host validates that metadata, exposes it in `/api/state`, and serves the module from `/shader-assets/{shaderId}/...`. Custom controls receive the current layer, declared parameters, `setParameter(id, value)`, and `requestReset()`. They still update the same manifest-declared parameters as the default React controls.
 
 ## Generated Files
 
@@ -374,62 +388,3 @@ If these variables are not set, CMake first looks under the private `video-io-3r
 - Add Aja input and output (Assuming i can get a hold of an aja card)
 - Add bluefish input and output (Assuming again card acess)
 - Endpoint to show OSC paths seperatly instead of a part of the control UI
-
-
-## Custom shader UI
-Extend the shader manifest contract
-Add optional UI metadata:
-
-"ui": {
-  "type": "webComponent",
-  "entry": "ui/controls.js",
-  "tag": "my-shader-controls"
-}
-Keep this optional. No custom UI means current default controls.
-
-Expose UI metadata in /api/state
-Add the parsed ui block to each shader/layer summary so the React app knows whether a layer has a custom control panel.
-
-Serve shader package UI assets safely
-Add a route like:
-
-/shader-assets/{shaderId}/ui/controls.js
-It should only serve files inside that shader package folder.
-
-Add a React host component
-Create something like ShaderCustomPanel.jsx that:
-
-dynamically imports/registers the custom element
-passes layer, parameters, and setParameter
-catches load/render failures
-falls back to the normal ParameterField grid
-Define the custom element API
-Keep it small and stable:
-
-element.layer = layer;
-element.parameters = layer.parameters;
-element.setParameter = (id, value) => {};
-element.requestReset = () => {};
-Custom UI should never bypass manifest validation.
-
-Add fallback and escape hatch
-Even if custom UI loads, provide a “Default controls” toggle per layer. That is the life raft.
-
-Add tests
-Backend:
-
-manifest parser accepts valid UI blocks
-rejects unsafe paths like ../
-/api/state includes UI metadata
-asset route refuses files outside the shader package
-Frontend:
-
-falls back when custom component fails
-calls /api/layers/update-parameter through the same path as default controls
-Document the contract
-Add a section to shaders/SHADER_CONTRACT.md with:
-
-manifest example
-custom element lifecycle
-available properties/functions
-rule: all controls must map to declared parameters