docs

docs/openapi.yaml

@@ -1079,6 +1079,9 @@ components:
         font:
           type: string
           description: Font asset id used by text parameters, when declared.
+        fontParameter:
+          type: string
+          description: Enum parameter id used to select a text parameter font at runtime.
         value:
           description: Current parameter value.
           oneOf:

shaders/SHADER_CONTRACT.md

@@ -592,6 +592,40 @@ float4 premultipliedText = drawTitleText(textUv, float4(1.0, 1.0, 1.0, 1.0));
 
 Text is currently limited to printable ASCII. `maxLength` defaults to `64` and is clamped to `1..256`. The optional `font` field references a packaged font declared in `fonts`; if no font is specified, the runtime uses its fallback sans-serif renderer.
 
+Text parameters can also choose their font from an enum parameter by setting `fontParameter` to that enum parameter's `id`:
+
+```json
+{
+  "fonts": [
+    { "id": "inter", "path": "fonts/Inter-Regular.ttf" },
+    { "id": "mono", "path": "fonts/Mono-Regular.ttf" }
+  ],
+  "parameters": [
+    {
+      "id": "font",
+      "label": "Font",
+      "type": "enum",
+      "default": "inter",
+      "options": [
+        { "value": "inter", "label": "Inter" },
+        { "value": "mono", "label": "Mono" }
+      ]
+    },
+    {
+      "id": "titleText",
+      "label": "Title",
+      "type": "text",
+      "default": "LIVE",
+      "font": "inter",
+      "fontParameter": "font",
+      "maxLength": 64
+    }
+  ]
+}
+```
+
+Every option `value` in the font selector enum must match a declared font asset `id`. The `font` field remains useful as the default/fallback font for the text parameter, while `fontParameter` lets operators switch atlases at runtime without adding shader-specific code.
+
 Trigger example:
 
 ```json
@@ -619,6 +653,7 @@ Parameter validation:
 - `color` must have exactly 4 numbers.
 - Enum defaults must match one of the declared option values.
 - Text defaults must be strings. Non-printable characters are dropped and values are clamped to `maxLength`.
+- Text `fontParameter` values must reference an enum parameter whose option values are declared font asset IDs.
 - Trigger values are incremented by the host when triggered. The shader sees the trigger count and last trigger time.
 - Non-finite numeric values are rejected.
 
@@ -800,6 +835,7 @@ For multipass shaders, these files reflect the most recently compiled pass. If a
 - Remember enum globals are integer indexes, not strings.
 - Declare every texture in `shader.json`; undeclared texture samplers will not be bound.
 - Declare packaged fonts in `shader.json` when text parameters should use a specific font.
+- For selectable fonts, use a text parameter `fontParameter` that points at an enum whose option values are font IDs.
 - Keep temporal history requests modest. They consume texture units and memory and are capped by runtime config.
 - If a parameter appears in the UI but not in Slang, the shader may still compile, but the control has no effect.
 - If a Slang name collides with a generated global, rename your parameter or local symbol.
@@ -815,5 +851,6 @@ Before committing a new shader package:
 - Texture files referenced by `textures` exist.
 - Font files referenced by `fonts` exist.
 - Enum defaults are present in their `options`.
+- Text `fontParameter` selectors reference valid font assets through their enum options.
 - Temporal shaders handle short or empty history gracefully.
 - The app can reload and compile the shader without errors.