Dynamic UI RFC

[hidden4003]

Dynamic UI (schema-driven parameter/form generation, rendering & validation, and conventions) — RFC (final)

Summary

Shoko already has a schema-driven UI mechanism: a plugin author decorates a C# configuration class with attributes, the server describes the resulting form, and the WebUI renders it — no hand-coded per-feature UI required. This exists end-to-end today, but coverage is thin: the WebUI implements only 3 of 9 documented element types, several cross-cutting behaviors the server can already express (visibility rules, badges, restart/env-var indicators) aren't rendered at all, and server-declared action buttons on a form are dropped entirely.

The server side of this contract is ShokoServer pull request ShokoAnime/ShokoServer#1414, now merged. It replaces the JSON-Schema-plus-extension-bag approach (x-uiDefinition) with a dedicated, render-ready UiDefinition document, served alongside the schema rather than folded into it. This RFC describes that merged shape, and is the reference the WebUI implementation will be built from.

This RFC proposes:

• Implement renderers for every element kind the UiDefinition document describes (section-container, boolean, integer, float, string, text-area, password, code-editor, enum, list, record, select, plus reference and unknown as structural/fallback cases) and the cross-cutting behaviors it carries on every element (size, visibility, badges, restart/env-var indicators, denied values).
• Render the server-declared action buttons a configuration form can already carry, including ones grouped into a named section and ones pinned to a container's start or end.
• Support proactively calling back to the server while editing, for the specific fields that say they need it, rather than either posting the whole document on every keystroke or never calling back at all.
• Support fields whose choices only the server can list — fetched on demand, from the current draft, instead of baked into the definition or embedded in the value.
• Generalize the mechanism beyond the Renamer page to two consumers: a settings page for arbitrary plugins (buildable now), and a parameter modal for invoking a plugin action, which has a concrete server-side contract to build against.

Throughout, the plugin developer controls the resulting UI by authoring the schema/attributes; the WebUI's job is to render it generically, not to hand-build a component per plugin.

Concepts

Three documents are involved, and keeping them apart is most of understanding this.

Document	Endpoint	Describes	Changes when
Definition	GET Configuration/{id}/UiDefinition	The type: what fields exist, how they're laid out, what they're called	The plugin is updated
Values	GET Configuration/{id}	One instance: what this user has saved	The user saves
Schema	GET Configuration/{id}/Schema	The validation contract	The plugin is updated

A renderer needs the first two. The schema stays the authority for server-side validation, and a client built on the definition never has to read it.

Type, not instance. A definition is generated once per type, before anyone's saved document exists, so it cannot say how many rows a list has, what keys a dictionary holds, or where any particular row sits. Three consequences that come up repeatedly:

• An action carries no path to invoke it at, because the container holding it may repeat as a list row where the path differs per row. The client knows which row it's rendering, so the client builds the path.
• A condition's path is relative to the object its element sits in, never absolute, so the same condition means something different in each row.
• A list's item is described once, and that one description renders every row.

Element. The unit of the definition. Every element carries a Kind discriminator naming exactly one renderer, plus the same cross-cutting fields regardless of kind: label, description, size, visibility, badge, restart and environment indicators, denied values, default, required and nullable. A leaf element (string, integer, enum, …) binds to a value; a composite one (section-container, list, record) holds other elements.

Container and structure. A section-container files its members in three maps and puts them back in order with Structure:

Structure: [ {item}, {floating-section}, {item}, {action} ]
                │           │               │        │
     Items ◄────┘           │               └────────┤
     FloatingSections ◄─────┘                        │
     Actions ◄───────────────────────────────────────┘

Each entry names which map to look it up in, so resolving one is an index rather than a scan. Nothing is grouped, sorted or filtered client-side: the order in Structure is the order on screen.

Two kinds of grouping, which are easy to confuse:

• A nested class is an ordinary item whose element happens to be a container. It labels itself from its own label, and recursing into it is the same component one level down.
• A floating section is a group the server assembled out of members that share a [SectionName], plus a default section for whatever is left when the layout needs one. It has a title, an optional description, its own Structure, and its own pinned actions. It is not a member of anything; it is a view over members.

Action. A button the class declared. Where it renders is decided by which list names it, never by a property on the action: a container's or section's StartActions/EndActions for a pinned button, or the structure itself for one inline among the fields. Invoking it needs the configuration id, the action's Name, and the path the client walked to reach it.

Live edit. A class can handle edits before anything is saved, to compute one field from another or fill a list of options. Because posting the whole document on every keystroke is not viable, the definition says where it is worth doing: a container carries HasLiveEdit and HasNestedLiveEdit, and an element carries ReactsToLiveEdit, the events an edit to that element is worth sending on. Empty means the form stays local.

What comes back is a result, not necessarily a document. It may carry JSON Patch operations against what was posted, and only does when the handler returned a configuration at all; it may instead, or additionally, carry messages to show, validation errors to attach to fields, a redirect, and flags such as whether to refresh. A handler that only validates, or only has something to say, returns no patch. The same result shape comes back from invoking an action, so one merge path covers both.

Options. Some choices are neither fixed by the type nor stored in the value: the set of installed plugins, the libraries that currently exist. An element the server can list such choices for carries HasOptions, and the client asks for them on demand, sending the draft it holds; the answer is a list of value-and-label pairs. Like a live edit, it reads the unsaved draft, so the choices can depend on what the user just typed.

Condition. A comparison the client evaluates against the draft the user is editing, not the saved document. It carries a path, an operator, and a value or set of values. It can descend into a nested object and never climbs out of the one it is declared in. An operator a client does not recognise is treated as unmet.

Reference. Where the element tree would recurse into itself, the server emits a reference pointing into the definition's own Definitions table. It is the only place a client has to resolve anything by name.

Value binding. An element's key is the property name in the values document, so an element's path is the chain of keys walked to reach it. One exception worth knowing: a select element is deliberately thin, because its options live in the value it binds to rather than in the definition, populated by the server.

Who decides what.

Decision	Made by
Which fields exist, what they're called, how they're grouped and ordered	The plugin author, through attributes on the class
Turning that into elements, sections, layouts and flags	The server, once per type
Chrome: what a tab, a field set, a row or a button looks like	The client

Motivation

This is not a from-scratch design. A generic mechanism already exists and is already wired up end-to-end for one consumer:

• Server: GET Configuration/{id}/Schema returns a JSON Schema, currently extended with an x-uiDefinition property describing how each field should render — element type, size, visibility rules, badges, restart requirements, env var overrides, etc. GET Configuration/{id} returns the current values.
• WebUI: src/components/Dynamic/{DynamicForm,DynamicSection,DynamicField,CodeEditor}.tsx consume that contract generically (keyed by configuration id, not hardcoded to any one feature).
• The only thing actually driving this today is src/pages/utilities/Renamer.tsx.

The gap is coverage, not architecture: the WebUI's elementType union documents nine element types, but only three are actually rendered (auto, which itself branches internally on JSON type to cover booleans/numbers/strings, password, and code-block) — everything else falls through to an "Unsupported element type" placeholder. Several cross-cutting behaviors the schema already models — visibility, badges, restart indicators, env-var overrides, denied values — aren't rendered at all yet.

Why the RFC targets the UiDefinition document, not the schema bag. The bag is hard to render from. Before the merge, its generator had a real defect: for a plain scalar list (e.g. CoreSettings.Import.VideoExtensions, a List<string>), the field meant to carry the list's item element type was initialized to a display size value and only conditionally overwritten, so for a simple scalar list it never was. A client reading it to decide how to render list items would be reading a value that means something else entirely. The same construction existed for record.

GET Configuration/{id}/UiDefinition fixes exactly this: a list or record's item element is a real, always-present child node, not something inferred from an overloaded field. Section grouping is computed server-side and positionally, conditions have real comparison operators, elements say which live-edit events they care about, and the server can list choices only it can enumerate. The same document shape is also served for actions (GET Action/{actionID}/UiDefinition) and parameters are accepted on action-invocation endpoints, which gives the plugin-action-parameter consumer (this RFC's original motivating use case) a real contract.

The legacy bag is still served for now. So that the released WebUI keeps working, the server still writes the few legacy x-uiDefinition entries today's dynamic form reads (sectionType and structure on the root, elementType and codeLanguage on its properties), for the renamer preset editor (and, per the server's own note, the metadata provider settings; this WebUI's only current consumer is the renamer page). The server marks this as legacy, to be removed once the WebUI moves to UiDefinition. New code should read UiDefinition only.

This RFC's target consumers are:

1. A settings page — a per-plugin settings surface generalizing the same mechanism Renamer.tsx already uses to other plugins. Buildable now. One thing to know when listing configurations: GET Configuration excludes hidden and base configurations unless asked, and on a running server every configuration reported IsHidden: true, including the core settings and the test plugin's seven. With the default filters the list was empty. A page that lists configurations has to pass hidden=True (and isBase=True where it wants those), or fetch a known configuration by its id.
2. An action-parameter modal — invoking a plugin-registered action with a real parameter UI instead of defaults-only. This now has a concrete server-side contract (GET Action/{actionID}/UiDefinition, plus parameter-accepting invocation endpoints) from Render-ready UI definitions for configurations and actions, plus a Roslyn analyzer for unrenderable shapes ShokoServer#1414, now merged; it returns the same document shape as the configuration endpoint.

The design intent behind both: the plugin developer controls the UI, not the WebUI team — a plugin ships a description of its fields, and the WebUI renders it generically. The purpose of this RFC is to replace src/pages/settings/plugin/PluginPageEmbed.tsx, which lets a plugin control its UI via a fully custom page embedded in an <iframe> (arbitrary HTML/JS). The iframe was the easiest way to render dynamic third-party UI in the WebUI, not a design to preserve: once this RFC is confirmed, iframe embedding should be considered legacy.

Also distinct from both of the above: a configuration class can already declare UI action buttons on its own settings form (e.g. "Test Connection"), separate from the action-modal consumer described above. The WebUI doesn't render these at all today — easy to conflate with the "plugin action modal" concept since both are called "actions," but they're different mechanisms serving different purposes.

Design

What this document is, and isn't

Everything below describes the definition the server generates for a configuration or action's type — labels, element kinds, layout, validation rules, conditions. It never carries any actual configuration values. Values are a completely separate document, fetched from a separate endpoint (GET Configuration/{id} for a configuration's current values), and that separation is structural, not incidental: a definition is generated once per type, before any specific document's array lengths or dictionary keys exist — it has no way to describe this particular user's saved data, only the shape any such document of this type would follow. Where an example below elides fields for brevity, it uses a // … fields omitted comment, never a placeholder property — nothing in this document ever holds a real value.

Element type renderers

The UiDefinition document uses a 14-member element-kind discriminator, with no auto member — the server always resolves authored intent down to one concrete kind before the document is served, so the client dispatches on that kind directly rather than inferring a render type from the underlying JSON type. The layout a list, record or select renders with is held to the same standard: it is always stated, never auto. Build order is still foundational-first: section-container unblocks the complex variants of list/record, so it goes first even though it isn't independently visible in the UI.

What this actually looks like on the wire. This example is an illustration trimmed from the real Core Settings payload of a running server (6.0.0-dev.531), checked field by field against it. It is drawn as if the AniDB area were the root: in the real payload that container is Root.Items.AniDb (section type minimal, with seven floating sections: Login, Download, Update, URLs, HTTP, UDP, AVDump), the root is a tab container whose Structure lists Image, Import, AniDb, Metadata, … as items, and StorageState is shown here only to illustrate an enum: in the real payload it sits one level further down, in AniDb.MyList.

// GET /api/v3/Configuration/{configID}/UiDefinition
{
  "ID": "19c7a5e2-…",
  "Name": "Core Settings",
  "Root": {
    "Kind": "section-container",           // concrete discriminator — no "auto"
    "SectionType": "tab",
    "ShowSaveAction": true,
    "HasLiveEdit": false,                  // this container has no handler of its own
    "HasNestedLiveEdit": false,             // ...and nothing below it does either
    "Items": {                              // every field lives here, however it's grouped for display
      "Username": {
        "Kind": "string",
        "Key": "Username",
        "Label": "Username",
        "Description": "AniDB username.",
        "Size": "normal",
        "Visibility": { "Default": "visible", "Advanced": false, "Toggle": null, "Disable": null },
        "Badge": null,
        "RequiresRestart": false,
        "EnvironmentVariable": { "Name": "ANIDB_USER", "AllowOverride": false },
        "ReactsToLiveEdit": [],             // no live-edit handler watches this field
        "HasOptions": false,                // true when the server lists this element's choices (see "Server-listed options")
        "Default": null, "IsRequired": false, "IsNullable": true, "DeniedValues": null
      },
      "Password": { "Kind": "password" /* … fields omitted, same base shape as Username */ },
      "MaxRelationDepth": {
        "Kind": "integer",
        "Minimum": 0, "Maximum": 5,        // constraints live ON the element now
        "Size": "small"
        // … fields omitted
      },
      "StorageState": {            // really Root.Items.AniDb.Items.MyList.Items.StorageState; shown flat for brevity
        "Kind": "enum",
        "Values": [                        // options pre-resolved — no schema round-trip
          { "Title": "Unknown", "Value": "Unknown" },
          { "Title": "HDD",     "Value": "HDD" }
        ]
        // … fields omitted
      }
      // nested objects inline as nested section-containers — no $refs to resolve
    },
    "Actions": {                            // every action button this container can show, however it's placed
      "Test": {
        "Name": "Test",                     // sent back to the server as `actionName` on invocation
        "Title": "Test",
        "Theme": "primary",
        "Size": "normal",
        "DisableIfNoChanges": false,
        "Toggle": null, "Disable": null
        // no "Position" field — where a button renders is which list names it, not a property of the action
      }
    },
    "FloatingSections": {                   // named groupings, referencing members already in Items/Actions above
      "Login": {
        "Title": "Login",
        "Description": null,
        "HasNestedLiveEdit": false,
        "StartActions": ["Test"],           // a pinned button, not attached to one field
        "EndActions": [],
        "Structure": [
          { "Name": "Username", "Kind": "item" },
          { "Name": "Password", "Kind": "item" }
        ]
      }
    },
    "StartActions": [], "EndActions": [],   // pinned buttons at the whole container's own top/bottom
    "Structure": [                          // root-level order — sections and any ungrouped members, interleaved
      { "Name": "Login",                "Kind": "floating-section" },
      { "Name": "MaxRelationDepth",     "Kind": "item" },
      { "Name": "StorageState",         "Kind": "item" }
    ]
  },
  "Definitions": {}                         // only populated to break reference cycles
}

Rendering a container is: walk its Structure; for a item/action entry, look the name up in Items/Actions (recursing the same way for a nested section-container); for a floating-section entry, look the name up in FloatingSections and recurse into its own Structure/StartActions/EndActions the same way. A member's position in the layout is entirely decided by which of these an entry names — nothing is filtered or grouped client-side, and each Kind maps 1:1 to a renderer so dispatch is a plain switch.

That example doesn't cover list, record, or select. The following come from the PR author's test plugin (https://github.com/revam/dotnet-shoko-plugin-genui-test, one configuration per level of reactivity, each member documented with what a tester should see), loaded on the same running server. The element shapes below match its GET …/UiDefinition output, and the values are what GET Configuration/{id} returned. The server writes nulls, so a select option without a group carries "GroupID": null rather than omitting it. Base fields every element carries (Size, Visibility, Badge, RequiresRestart, EnvironmentVariable, ReactsToLiveEdit, HasOptions, Default, IsRequired, IsNullable, DeniedValues, Description) are omitted for brevity.

// list — a List<string> with UniqueItems and Sortable (test plugin: Collections.Strings)
{
  "Kind": "list",
  "Key": "Strings",
  "Label": "Strings",
  "ListType": "flat",                       // always stated; never "auto"
  "Item": { "Kind": "string", "MinLength": null, "MaxLength": null, "Pattern": null, "Format": null, "Key": null, "Label": "" },
  "Sortable": true,
  "UniqueItems": true,
  "HideAddAction": false,
  "HideRemoveAction": false,
  "MinItems": null,
  "MaxItems": null,
  "ItemTitlePath": null,                    // a scalar item has nothing to label itself with
  "ItemCategoryPath": null
}
// its value: ["one", "two"]

// list of classes — a List<TestRow> drawn as tabs (test plugin: Collections.TabRows)
{
  "Kind": "list",
  "Key": "TabRows",
  "Label": "Tab Rows",
  "ListType": "complex-tab",                // authored here; a class-typed item otherwise resolves to complex-inline
  "Item": {
    "Kind": "section-container",
    "SectionType": "field-set",
    "PrimaryKey": "ID",
    "Structure": [ { "Name": "ID", "Kind": "item" }, { "Name": "Title", "Kind": "item" },
                   { "Name": "Value", "Kind": "item" }, { "Name": "Mode", "Kind": "item" } ]
    // … Items (one element per member), Actions, FloatingSections and the base fields omitted
  },
  "ItemTitlePath": "Title.Title",           // relative to each row's own value
  "ItemCategoryPath": "Title.SubTitle",
  "Sortable": true,
  "UniqueItems": false,
  "HideAddAction": false,
  "HideRemoveAction": false
}
// its value: [ { "ID": "75094eac", "Title": { "Title": "Row", "SubTitle": "A complex entry" }, "Value": "", "Mode": "Slow" } ]

// record — a Dictionary<TestMode, int> keyed by an enum (test plugin: Collections.Weights)
{
  "Kind": "record",
  "Key": "Weights",
  "Label": "Weights",
  "RecordType": "flat",                     // "complex-dropdown" or "complex-tab" when the value is a class
  "KeyItem": { "Kind": "enum", "Label": "Key",
               "Values": [ { "Title": "Slow", "Value": "Slow" /* … Description, Alias, AliasValues */ },
                           { "Title": "Middle Ground", "Value": "Balanced" }, { "Title": "Fast", "Value": "Fast" } ] },
  "Item": { "Kind": "integer", "Minimum": null, "Maximum": null, "Label": "" },
  "ItemTitlePath": null,                    // null on both: a row is labelled by the key it's stored under
  "ItemCategoryPath": null,
  "Sortable": true,
  "HideAddAction": false,
  "HideRemoveAction": true                  // authored: no remove button
}
// its value: { "Slow": 1 }

// select — the DEFINITION side is thin by design (test plugin: Selects.Grouped).
// The options live in the VALUE it binds to (see Design below)
{
  "Kind": "select",
  "Key": "Grouped",
  "Label": "Grouped",
  "SelectType": "flat-list",                // "checkbox-list" when MultipleItems is true; never "auto"
  "MultipleItems": false
}
// The bound value, elsewhere in the configuration document, at the same key —
// cased like everything else in the document:
"Grouped": {
  "Options": [
    { "Label": "Ex",  "GroupID": 1, "Value": "x", "IsSelected": false, "IsDefault": false, "IsDisabled": false },
    { "Label": "Why", "GroupID": 1, "Value": "y", "IsSelected": false, "IsDefault": false, "IsDisabled": false },
    { "Label": "Zed", "GroupID": 2, "Value": "z", "IsSelected": false, "IsDefault": false, "IsDisabled": false }
  ],
  "Groups": [ { "ID": 1, "Label": "First", "IsDisabled": false }, { "ID": 2, "Label": "Second", "IsDisabled": false } ]
}

The numbered build order below matches the examples above:

1. section-container — walk Structure, dispatching each entry to Items, Actions, or FloatingSections as described above; a FloatingSections entry is itself a small container with its own Structure/pinned actions, so the same recursive component handles both levels. Recursing into a nested section-container (e.g. a nested configuration object) is the same component the top level already uses, just called one level deeper. A container whose section type is checkbox also carries ToggleMember: the key, in its Items, of the boolean that turns the section on, to be drawn as the section's own checkbox rather than as a field inside it.
2. list — its layout is one of: flat (an editable array — one field per index, add/remove/reorder controls per the container's own hide-add/hide-remove/sortable flags), enum-checkbox (a checkbox per member, when the item kind is enum), or complex-dropdown / complex-tab / complex-inline (each item is a full nested section-container, selected via dropdown / tabs / stacked inline respectively). The server always states one: it resolves an unspecified layout before serving — a list whose item is a class of its own comes out complex-inline, anything else flat — and never overrides one the author chose, so a list of enums is flat unless the author asked for enum-checkbox, which makes the shared checkbox component below opt-in rather than inferred. Each row is labelled by reading ItemTitlePath (and, as a line beneath it, ItemCategoryPath) relative to that row's own value; both are null when the item has nothing to label itself with. A class says what it calls itself by holding a small title component (a Title and an optional SubTitle); where it says nothing, the server falls back to the member marked as its key. In every case, the item's own element description is a real, always-present child node — no inferring the item's kind from a separate, possibly-stale field. A list whose Item has options (see "Server-listed options") offers those choices for each entry. A [Flags] enum renders as exactly this kind of list. Real examples: OfflineImporter.AutoMatchRules/ParseRules (complex), CoreSettings.Import.VideoExtensions/Image.ImageTemplateUrls (simple scalar).
3. record — same shape as list but keyed by a string/enum key instead of an index, and carries two child nodes instead of one: one describing the key, one describing the value — named so a renderer can treat a list entry's payload and a record entry's payload identically. A record's layout is flat, complex-dropdown or complex-tab, resolved the way a list's is (a class-valued record comes out complex-dropdown, anything else flat). Its entries are labelled the way a list's rows are — ItemTitlePath and ItemCategoryPath sit on the record element too, relative to a value — and an entry with neither is labelled by the key it's stored under. Each side is described from its own type: a record keyed by one enum with another enum as its value describes each side with its own members (checked with the server's definition builder on such a type, not on a running server). Either child can have server-listed options: a dictionary keyed by folder name, say, has a KeyItem that lists the folders.
4. enum — a fixed list of named values, each carrying its own display title, optional description, wire value, and the alias names/values that collapsed onto it as arrays (so a value stays findable by every name it's known by, e.g. a legacy alias for a renamed option — empty when it has none, never a single joined string). There is no flag on the element for combinable bit flags any more: a [Flags] enum is described as a unique list whose item is an enum of its single-bit members, so it takes the same path as any other list of enums (checkbox layout when the author asked for enum-checkbox, plain rows otherwise) and no separate renderer. Its value is an array of member names, [] for none; a member that combines several bits is never listed or written. This has been checked for a flags enum used directly as a member of a section; a flags enum nested inside a list or record was not found to follow the same description (its entries came out listing the zero and combined members and not marked unique), so a renderer should not rely on the rule there, and a plugin author who needs one can wrap it in a class. The previous text/number forms are still accepted by the server on input but are not what the schema describes, so a client should only ever send the array. If an enum element also has server-listed options, the options narrow it: offer only the values returned, labelled the way the static list labels them. Real examples: OfflineImporter.Mode, OfflineImporter.MatchType, CoreSettings.AniDb.MyList.StorageState.
5. select — a selection component whose options are supplied by the server as part of the configuration value itself, not as part of the element's own description — the definition only carries the layout and whether multiple selection is allowed. The layout is always stated: flat-list when one choice is allowed, checkbox-list when more than one is, unless the author chose otherwise. flat-list → existing select component; checkbox-list → the same shared checkbox-list sub-component as enum/list's checkbox variants. If a compact multi-select for long option lists is needed later, a tag-style control (selected values as removable chips, options searchable in a dropdown) is the preferred shape; it would need its own layout value from the server and is not part of this RFC. There's deliberately no field on the definition naming what a select depends on — instead, the element's own ReactsToLiveEdit (see Reactivity below) says which events should trigger a re-fetch of its populated options, and the recommended authoring pattern keeps the selected choice in its own scalar property with a nullable options payload populated on load/live-edit and cleared once a choice is made (or stripped in a save handler) — so a probed-but-unselected option list never gets persisted into the saved configuration document. The value this element points at (see the example above) is cased like the rest of the document — Options, Groups, and each option's Value/Label/IsSelected/IsDefault/IsDisabled/GroupID — so a generic "read the value at this element's key" binding needs no special case for it. A select carries no denied values of its own: its options live in the value, and the server files no denied values on it. select and server-listed options are separate mechanisms: a select carries its options inside the value it binds to, whereas an element with HasOptions has them fetched on demand. Real example: OfflineImporter.AutoMatchRule.LocationRules[].ManagedFolderSelector.
6. password — the input itself is trivial: a masked single-line text input, no new component needed. Produced by either of two server-side markers on the underlying property, so no client-side distinction is needed between them. The value it binds to is another matter — see "Masked secrets" below. Real example: CoreSettings.AniDb.Password.
7. text-area — needs one small new component (no multiline text input exists in the input library today) — a native <textarea> styled to match the existing single-line input. Real example: OfflineImporter.CustomParseRule.Regex.
8. boolean/integer/float/string — what today's code handles as a single auto case branching on JSON type becomes four concrete, independently-dispatched kinds. Functionally equivalent to what's already implemented for these (checkbox / number input / number input / text input) — integer and float both carry their own min/max bounds directly on the element (as long?/double? respectively), so neither needs a schema round-trip for validation range — just reached by matching the element kind directly rather than by reading the underlying schema type, which removes a layer of inference the current code needs and the new document doesn't.
9. code-editor (the new name for what's code-block today) — same Monaco-based editor already implemented, with the language to highlight and whether to auto-format on load carried directly on this element instead of a general-purpose flag.
10. reference — new: a pointer into a top-level table of hoisted element definitions, emitted wherever the element tree would otherwise recurse into itself (e.g. a self-referential structure). Needs a resolution step with no equivalent in the current renderer: look the pointed-to key up in that table and render it in place.
11. unknown — new: the document's own "the server couldn't classify this" placeholder, carrying the raw schema type it failed to map. Replaces today's generic "Unsupported element type" fallback with one that reports what specifically wasn't understood.

Masked secrets

The server never sends a stored secret back out. In every outward-facing configuration read — including the value a password element is bound to — it replaces each secret that is set with a placeholder (currently ***SECRET-UNCHANGED:<fingerprint>***, the fingerprint being a keyed hash specific to that install), and on validate, save, action and live-edit requests it swaps a placeholder back for the stored secret before anything reads the document. The same two markers ([PasswordPropertyText] and [DataType(DataType.Password)]) that produce a password element are the ones that mark a secret, so a password element is where a placeholder shows up; the definition carries no separate marker beyond the password kind. A secret that is null or empty goes out as it is, so "nothing set" still looks different from "withheld": on a read, a non-empty value in a password element means a secret is stored, and a client that only wants to show that never needs to recognize the placeholder.

What that asks of the renderer:

• Treat the placeholder as an opaque string. Don't trim, transform, reveal or validate it, and if the user hasn't touched the field, send back exactly what was received. An edited field sends the new plaintext; an explicit null or empty string clears the stored secret; leaving the property out of a document leaves it alone.
• Don't parse it, or key UI state on its prefix. Its format has already changed once while the PR was open (a fixed string, then one carrying a fingerprint), and the server's own documentation tells its consumers to use a recognizer helper rather than compare strings.
• In a list of secrets, a placeholder belongs to its entry. It has to move with that entry when other rows are reordered or removed, and a client must never make one up: inside a list the server matches each placeholder to a stored secret by its fingerprint, and one that matches nothing is rejected with a validation error keyed by that entry's path — the same routing as any other validation error (unknown paths go to a form-level bucket). A placeholder for a secret that has nothing stored behind it any more is rejected the same way.

Server-listed options

An element that lets the user pick among values only the server can enumerate carries HasOptions: true. It sits on the element that renders the choice: a scalar member, a list's Item, or a dictionary's KeyItem (the keys) or Item (the values). No new element kind is involved: a dictionary whose keys and values are both listed is an ordinary record whose KeyItem and Item both have options.

An example from the server's own documentation. The server-side documentation for this feature authors the following (a configuration with a library choice, a list of extra libraries, and a dictionary from folder name to mode; TestMode is an enum). Real captured output from a running server follows it.

public int LibraryId { get; set; }
public List<int> ExtraLibraryIds { get; set; } = [];
public Dictionary<string, TestMode> ModeByFolder { get; set; } = [];

[OptionsProvider(nameof(LibraryId), nameof(ExtraLibraryIds))]
public async Task<IReadOnlyList<SelectOption<int>>> ListLibraries(ILibraryService libraries)
    => (await libraries.GetAll()).Select(x => new SelectOption<int>(x.ID, x.Name)).ToList();

[OptionsProvider(nameof(ModeByFolder), Target = OptionsTarget.Keys)]
public string[] ListFolders(IFolderService folders)
    => folders.GetNames();

[OptionsProvider(nameof(ModeByFolder))]
public TestMode[] ListModes([OptionsKey] string folder, IFolderService folders)
    => folders.IsReadOnly(folder) ? [TestMode.Read] : [TestMode.Read, TestMode.Write];

What the definition then says (a list, a record and a scalar member, as the test plugin's equivalents come back from a running server; the field names and HasOptions placement are the point):

"Port":         { "Kind": "integer", "HasOptions": true /* … fields omitted */ },
"ExtraLibraries": {
  "Kind": "list",
  "Item": { "Kind": "integer", "HasOptions": true /* … fields omitted */ }
  // the list itself has HasOptions false
},
"PortsByName": {
  "Kind": "record",
  "KeyItem": { "Kind": "string",  "HasOptions": true /* … fields omitted */ },
  "Item":    { "Kind": "integer", "HasOptions": true /* … fields omitted */ }
  // the record itself has HasOptions false
}

And the shape of an answer, from the server's own test for a labelled provider (Tags, whose provider returns one option with a label and one without); real answers follow below:

// POST /api/v3/Configuration/{configID}/Options?path=Tags
[ { "Value": "a", "Label": "Alpha" },
  { "Value": "b", "Label": "b" } ]      // no label given: the value as text

Captured from a running server. These come from a server running 6.0.0-dev.531, built after the pull request merged, with the PR author's test plugin (https://github.com/revam/dotnet-shoko-plugin-genui-test) loaded. They are unmodified response bodies.

The core Plugins settings are the first in-tree user of the attribute. EnabledPlugins is a dictionary from plugin name to a boolean, and only its keys have options; Priority is a list of plugin names whose entries have options:

// GET /api/v3/Configuration/{coreSettingsID}/UiDefinition  (Root.Items.Plugins.Items.EnabledPlugins, fields trimmed)
{ "Kind": "record", "RecordType": "flat",
  "KeyItem": { "Kind": "string", "Label": "Key", "HasOptions": true, "IsRequired": true /* … */ },
  "Item":    { "Kind": "boolean", "HasOptions": false /* … */ },
  "HasOptions": false /* … */ }

// POST /api/v3/Configuration/{coreSettingsID}/Options?path=Plugins.EnabledPlugins   (no body)
[ { "Value": "Shoko.Server", "Label": "Shoko Core" },
  { "Value": "Shoko.Plugin.Tmdb", "Label": "TMDB" },
  { "Value": "Shoko.Plugin.WebAOM", "Label": "WebAOM" } /* … */ ]

The test plugin's dictionaries show each path form against real answers:

// path=Options.PortsByName            → the dictionary's keys
[ { "Value": "web", "Label": "web" }, { "Value": "api", "Label": "api" }, { "Value": "metrics", "Label": "metrics" } ]

// path=Options.PortsByName["web"]     → the values for that key
[ { "Value": 8000, "Label": "8000" }, { "Value": 8001, "Label": "8001" }, { "Value": 8002, "Label": "8002" } ]

// path=KeyedByID.ModeByPlugin["<guid>"]   → enum values, relabelled by the provider
[ { "Value": "Slow", "Label": "Slow and steady" }, { "Value": "Balanced", "Label": "Steady" }, { "Value": "Fast", "Label": "Fast lane" } ]

// path=Options.Rows[0].Choice         → a field inside a list entry
[ { "Value": "item-1", "Label": "item-1" }, { "Value": "item-2", "Label": "item-2" }, { "Value": "item-3", "Label": "item-3" } ]

Errors come back as a 400 validation problem keyed by member path, and three are worth knowing. A list's own path takes no options (Options.Rows answers that its values "take no options"; ask for Rows[0].Choice). A dictionary entry whose key is not valid for the key type is rejected (TagsByMode["x"]: "x" is not a valid TestMode key; a valid key such as ["Slow"] answers). A provider can refuse the draft, and the error may be keyed to a different member than the one asked about (RemoteLibrary with no API key answers with an error on Options.ApiKey: "Set an API key to list the remote libraries.").

The answers above were requested without a body, so they reflect the saved configuration. Requests carrying an edited draft are shown under "What the responses look like".

Fetching. One route per form: the client appends /Options to the form's own route — /api/v3/Configuration/{configID}/Options for a configuration, or the route it invokes an executable action on with /Options appended, such as /api/v3/Series/1234/Action/{actionID}/Options (the series, episode, group or file is set on the action for the options provider to use). It is a POST; the body is optional and is the current draft (the configuration being edited, or the parameters entered so far for an action) — when it is left out the saved configuration is used — and path names the field the options are for. Send the draft whenever the user has unsaved edits, since a provider can depend on them:

path	Lists
LibraryId, Nested.Mode	A plain field
ExtraLibraryIds	A list's entries
Rows[2].Name	A field inside a list entry (the provider runs on that entry). A list's own path, Rows, is not accepted when only its entries' fields have options
ModeByFolder	A dictionary's keys
ModeByFolder["Anime"]	The values for that key (the key must be valid for the key type)

The key in the last row need not be saved yet: for a new entry the client picks the key first, then asks for that key's values.

Answer. An array of { "Value": …, "Label": "…" } in the order the provider returned it. Value is serialised the way the member itself is (so text for a Guid, an array entry for a flag enum), and Label is always set: the provider's own label, else the enum member's name as the form already shows it, else the value as text. An empty array means there is nothing to choose right now. A refusal comes back as the usual validation problem keyed by member path (for example, "set an API key first").

What a renderer does with it:

• Fetch the options when the element is shown, and again after an edit that could change them. The provider sees the draft, including unsaved edits, so one field's choices can depend on another.
• Show a stored value by the label of the matching option everywhere it appears, not only inside the picker — a dictionary keyed by Guid should show names rather than identifiers. Fall back to the raw value when it is not listed, such as a plugin that has since been uninstalled.
• Don't expect server-side search. A provider returns its full current list and the client filters locally.
• Treat a dictionary's key options and value options as independent requests.

Option values can be primitives, enums, the usual text round-trip types (Guid, dates, TimeSpan, Uri) and any type that parses from text.

Cross-cutting behaviors

Every element — regardless of kind — carries the same set of cross-cutting fields, so these are handled once, generically, rather than per element type:

• Size — normal/small/large/full. small uses a compact input in place of the normal one for string/number fields; large/full widen the field's container instead of swapping components.
• Visibility — three parts: a default state (visible/hidden/read-only), an advanced flag (hidden behind a section-level "Show advanced" toggle), and two independent reactive conditions: a disable condition, and a visibility-switch condition that additionally carries which visibility state to switch to while it holds (so it isn't limited to toggling hidden/visible — it can switch to read-only too). A condition compares a dotted path (which may descend into a nested object's own members, but can never climb out of its enclosing object and can never point through a list or record index) against a value, or a list of values, using one of: equals (the default), not-equals, is-empty, is-not-empty, in, not-in, greater-than, less-than, contains. Resolution is per-instance when the condition sits inside a list/record item, always evaluates against the client's current unsaved draft rather than the last-saved document, and an operator the client doesn't recognize should be treated as unmet. Deliberately out of scope: combining more than one condition with AND/OR — every case identified so far is covered by the operator list above, and supporting real composition would need a bigger authoring-model change (conditions can't nest as currently authored) than the cases justify.
• Badge — a small pill next to the field's label, carrying its own text and a color theme, mapped onto the existing badge component's theme classes.
• Description — rendered today as a subtitle under the field; still needs a tooltip variant for when small sizing leaves no room for a subtitle. The server-side generator trims and unwraps this text at the source (no leftover documentation-comment whitespace or mid-sentence line wraps), so the client needs no defensive trimming. Descriptions may also contain Markdown — the server converts XML-doc tags to it and keeps blank lines as paragraph breaks — so render them as Markdown rather than as plain text.
• Requires-restart indicator — an icon + tooltip next to the label when set.
• Environment-variable override — when a value is backed by an environment variable, show an indicator; disable the field entirely unless the variable is explicitly marked overridable from the client.
• Denied values — values to exclude from an option list before rendering. They only appear on an element that holds a value a denied one could match: authored on a collection they describe its entries, so a list carries them on its item and a record on its value, while a container, a reference or a select carries none. In practice enum filtering is the only case — an enum's options are part of the definition itself, so filtering them is a direct list operation — and nothing else hands the client values to filter. A flag enum denies individual entries only.
• Auto-format-on-load — now scoped specifically to the code-editor element (rather than a general flag): trigger a formatting pass once the editor mounts with a value, instead of leaving the raw text as authored.

Also newly available on every element, worth designing the renderer to lean on rather than cross-referencing the JSON Schema separately: a pre-resolved label, an optional longer description, a default value (what a freshly constructed instance holds, or a declared default; null for a nested class, a password, or no value), and whether the element is required/nullable. A client built against this document shouldn't need to consult the JSON Schema for anything except the server-side-authoritative validation pass.

Config-level action buttons

A configuration's form can already declare its own action buttons (e.g. "Test Connection"), each identified by a Name sent back to the server as actionName on invocation. An action renders wherever it's named, not according to a position field on the action itself: a pinned button appears in its container's or floating section's own StartActions/EndActions list, and an inline one is named by the structure. An action cannot be attached to a single field's row. A client never filters by a position value — placement is entirely a function of which list contains the action's name. Beyond that, each action carries a title/description/theme/size, an optional icon, a condition controlling whether it's shown (with the same visibility-switch shape described above) and a separate one controlling whether it's disabled, and a flag to disable the button while the configuration is unmodified.

On click: submit the current in-memory configuration to the server along with the action's Name (as actionName) and the field/section path it's attached to. There's no resolved path on the action's own definition — a definition describes a type, not a specific instance, and the same container can repeat as a list item or a record value where the path differs per row; only the client, while rendering, knows which row it's currently looking at. So the client builds path from the container chain it descended through to reach this action, the same way it already has to track which row of a list or record it's rendering — this is deliberate, not a gap to fill later. The response can carry a partial or full configuration to merge into local state (delivered as an RFC 6902 JSON Patch against what was submitted, so a removal is expressed unambiguously rather than inferred from an absent key), messages to toast, a location to navigate to, and validation errors to surface inline — respecting a flag for whether to keep any validation errors already showing.

Reactivity (proactive live-edit calls)

Beyond an on-submit or on-click action, a configuration can declare a live-edit handler that computes something in response to an edit before the form is saved (e.g. deriving one field's value from another). Calling that handler on every keystroke, for a large configuration, would mean posting the entire document dozens of times a second — so the definition carries enough signal to call back only when it's actually worth it:

• A container carries HasLiveEdit (this class itself handles live edits) and HasNestedLiveEdit (something below it does, even if this level doesn't); a floating section carries its own HasNestedLiveEdit the same way, so one tab can be reactive while its siblings aren't.
• An individual element carries ReactsToLiveEdit: the specific events (edited, focused, unfocused, view-changed, new-value, clicked, or all, written as those lowercase, hyphenated strings) that make an edit to that element worth sending a request for. Empty means nothing is listening, and the form stays purely local for that field.

A client should only call the live-edit endpoint for a field whose ReactsToLiveEdit is non-empty, on the events it names — turning what would otherwise be "post the whole form on every keystroke, or never call this at all" into a small, targeted set of requests. Two details of what happens once a request is sent. Every handler on the edited path runs, innermost first, so a class coordinating what its nested types do hears about an edit to one of them; each handler is handed what the previous one returned, their messages are collected in the order they were produced, their validation errors are merged by key, and the response is still a single patch. And a live edit that names a path which doesn't resolve is a no-op — an empty result, not an error — which is what a list row still being composed client-side looks like, so reactive requests can safely be treated as best-effort. An explicitly invoked action is stricter: pressing a button on something that isn't there is still an error.

No ordering guarantee between parallel live-edit requests. A monotonic revision counter on the live-edit/action-result response was proposed so that parallel requests from the UI, arriving at the server in a different order than they were sent, could be told apart. It has been decided not to build it: if out-of-order requests turn out to be a real problem in practice, they will be dealt with then.

What the responses look like

Captured from a running server (6.0.0-dev.531 with the PR author's test plugin loaded). Live-edit, action and validate calls all answer with the same envelope, and every field is always present:

// POST /api/v3/Configuration/{configID}/LiveEdit?reactiveEventType=edited&path=Source   (body: the draft, with Source = "hello")
{ "ShowSaveMessage": false, "Refresh": false,
  "PatchOperations": [ { "value": "Edited at \"Source\" (7:16:12 PM)", "path": "/LastEvent", "op": "replace" },
                       { "value": "olleh",                               "path": "/Mirror",    "op": "replace" } ],
  "Messages": [], "ValidationErrors": null, "KeepExistingValidationErrors": false, "Redirect": null }

• Patch operations are JSON Patch against the body that was posted, with lowercase op, path and value (a JSON Pointer such as /Nested/Echo). A nested handler's patch comes back in the same list (Nested.Value edited → /LastEvent and /Nested/Echo). PatchOperations is null when the handler returned nothing to change and may be an empty array when a handler ran and changed nothing; treat both as "no patch".
• An event nobody handles is an ordinary success. Editing a member no handler watches, a new-value for a row with nothing to say, and a path that does not resolve (Rows[5].ID) all answered 200 with the empty envelope above, not an error.
• A button (POST …/PerformAction?actionName=<Name>&path=) answers in the same shape. Seen: a patch (FlipAction → /IsAdvanced and /Kind); "ValidationErrors": { "Required": ["Set by the \"Refuse\" action."] } keyed by member path; "ShowSaveMessage": true; "Refresh": true (reload the form); "Redirect": { "Location": "https://…", "OpenInNewTab": true }; and Messages as a list of { "Title"?, "Message", "Theme" }, where Title is absent on an untitled message and several can arrive at once.
• Validate (POST …/Validate, body: the draft) answers ValidationErrors keyed by member path when a rule refuses a value ({ "ValidatedText": ["…"], "Count": ["…"] }) and null when it accepts.
• An options request with a draft body sees the unsaved edits. With ApiKey set in the posted draft, Options.RemoteLibrary answered with two libraries instead of the "set an API key" refusal; with HideFast set, a mode list lost its Fast entry.

Action-parameter modal

Distinct from the config-level action buttons above: invoking a plugin-registered action (of any scope) can now request its parameter form the same way a configuration requests its own — the same document shape describes both, so no special-casing is needed to render one versus the other. An action's parameter set doesn't vary by what it's invoked against, so one lookup covers a globally-scoped action and a series/episode/file/group-scoped one alike. A listing of available actions should be checked for whether an action takes parameters at all before offering to open this modal, to avoid an unnecessary round-trip for the (currently more common) parameterless case.

A parameter can have server-listed options too, fetched from the action's own route with /Options appended, with the parameters entered so far as the body (see "Server-listed options").

Invocation accepts an optional parameter body — omitting it still invokes exactly as a parameterless action always has, so this is additive to existing invocation, not breaking. A body that fails validation should surface as inline field errors on the modal, the same treatment config-level action buttons above already need for their own validation-error responses.

What invocation answers, captured from a running server with the test plugin's actions (POST /api/v3/Action/{actionID} for a global action, POST /api/v3/Series/{seriesID}/Action/{actionID} for a scoped one):

Case	Response
Valid body	200, empty body (the action is accepted; there is no result to show)
Required parameter missing, or no body at all	400, { "errors": { "Message": ["Property Required"] }, … }
String shorter than its minimum	400, { "errors": { "Message": ["String Too Short"] }, … }
Value not in an enum	400, { "errors": { "Mode": ["Not In Enumeration"] }, … }
The action's own validation refuses	400 with a plain-text reason as the body (Refused on request.), not a validation problem and with no member path
Entity does not exist	404, plain text (Series not found.)
Scoped action whose parameters are all optional, no body	200

Two consequences for the modal. The 400 validation problem is the usual ASP.NET shape, keyed by member name, but the messages are the schema validator's own terse keywords (Property Required, String Too Short, Not In Enumeration), so a client that wants readable text should map them itself, using the constraints it already has from the definition. And a refusal from the action's own code arrives as plain text, so the modal needs a place to show a message that belongs to no field; check the content type rather than assuming JSON.

Bulk invocation is out of scope for the first implementation. The server has bulk-invocation endpoints for scoped actions ({actionID}/Group/Bulk, /Series/Bulk, /Episode/Bulk, /File/Bulk) that apply one set of invocation parameters across several entities at once, rejecting the whole call if any entity ID doesn't resolve. The PR's author has said the WebUI does not need them for a first implementation: they were added to the API so the WebUI can adopt them later without a server upgrade, for example after a stable server release. This RFC therefore doesn't design a bulk flow. For whoever picks it up: the bulk body is the list of IDs plus optional parameters limited to booleans, numbers and string lists (no nested objects), and the bulk routes have no /Options route of their own, since server-listed options are fetched per entity on the single-entity routes (an action whose choices are, say, the titles of the series it runs on has nothing to list when several series are selected).

[revam]

There's a draft PR on the server side that this RFC needs to account for:
ShokoAnime/ShokoServer#1414. It doesn't compete with what's proposed — the RFC adds renderers, this
changes the input those renderers consume — but it does change that input out
from under the current one. It's a draft specifically to collect feedback first,
and it's open so the client side can be built against the new shape before the
server side merges.

What it is: a UiDefinition DTO served from
GET /api/v3/Configuration/{configID}/UiDefinition, alongside the existing schema.
Same information, shaped for rendering rather than validation.

This replaces x-uiDefinition rather than sitting beside it. The bag is cut
down to the five entries the server's own validator reads back
(elementType, requiresRestart, envVar, envVarOverridable,
enumDefinitions); everything presentational is gone, and the class-level bag
with it. Worth being blunt about what that costs: the current config form reads
schema['x-uiDefinition'].sectionType and .structure unguarded, so it doesn't
degrade — it throws. DynamicField guards and renders nothing; the renamer script
editor loses the code-block lookup it finds its editor by.

This is a dev-channel change, so the two sides don't have to land in lockstep,
and the PR is open now rather than merged so the renderer work can be built
against UiDefinition first.

Against the proposed build order

1. section-container — Items is a map of already-resolved child elements
keyed by the property name they live under in the document, so recursing doesn't
mean re-resolving $ref at each level and finding a child doesn't mean scanning
an array. Actions is the same, keyed by action ID. A Structure entry carries
that key plus a Kind of item or action naming which map to look in. Both
maps enumerate in authored order, so rendering the values in order already gives
you the layout; Structure is for when you want the two interleaved, which is
what allows buttons between fields rather than only top/bottom.

Collections follow the same vocabulary: a list has one Item, and a record
has a KeyItem and an Item — the record's value takes the same name as a list's
entry, so the payload of both renders through one path.

2. list — worth knowing before building against it: listElementType is
initialised to a DisplayElementSize, not an element type, and only
conditionally overwritten. For List<string> the server sends
listElementType: "normal", which isn't a member of DisplayElementType at all.
So the "auto/unset with scalar listElementType" branch would be matching a
value that means something else. On the DTO it's replaced by a real Item
node. Same for recordElementType and selectElementType.

3. record — flagged as provisional pending a live schema example. Two
concrete findings: a dictionary's key type and value type go through the same
property key, so for an enum-keyed dictionary the value element comes back as
an enum carrying the key's members, and the key itself renders as free text.
Both are fixed in the DTO — Dictionary<SomeEnum, int> yields a proper
KeyItem to constrain keys against.

4. enum — Title / Description / Value, with Alias / AliasValues
carried through so a value stays findable by every name it's known by
(Database.Type aliases MariaDB onto MySQL). DeniedValues is on the element
for filtering.

5. select — UiSelectElement carries Options (value, label, optional
group and description) and Groups, plus MultipleItems and the authored
SelectType. The working example is the offline importer's managed-folder
picker: a SelectComponent<int> repopulated from IVideoService inside a
[ConfigurationAction(LiveEdit)] handler, paired with an inverse-condition
visibility toggle so the free-text field and the picker swap places. That is the
shape to render against — server-populated, refreshed on live edit, not static.

6/7. password / text-area — straightforward Kind discriminants.

Cross-cutting behaviours

All first-class fields: Size, Visibility (with Toggle / Disable), Badge,
RequiresRestart, EnvironmentVariable { Name, AllowOverride }, DeniedValues.
Two server-side notes that apply whichever input you render from:

• visibility.toggle.inverseCondition was never being emitted, though the
  disable toggle beside it always was and both are read as non-optional — so an
  inverted visibility toggle rendered backwards and looked like a client bug.
  Fixed on master; anyone implementing visibility wants a server at or after
  that commit.
• DisplayButtonPosition was broken. The enum aliased Top/Left onto one
  value and Bottom/Right onto another with [EnumMember] only on the
  canonical names, so resolution for a duplicate was unspecified — Top
  serialised as "Left", End as "Right". The PR reduces it to "auto" /
  "start" / "end", which is what an action-button position mapping should
  expect.

On the action modal

The RFC lists that consumer as blocked on a separate plugin-action RFC. On the
server side that's now unblocked end to end:

• GET /api/v3/Action/{actionID}/UiDefinition returns an action's parameter form,
  for actions of any scope, in the same UiDefinition shape as a configuration —
  so a renderer needs no special case.
• POST /api/v3/Action/{actionID} and the four scoped variants accept an optional
  parameter body.
• ActionInfo.HasParameters tells the listing whether an action has a form worth
  opening, without shipping the definition on every entry.
• The body is validated against the action's schema before anything runs, and
  unknown properties are rejected rather than silently dropped.

Two shipped actions already declare parameters (DownloadAllImagesAction,
PurgeAllTmdbLinksAction), so there's something real to render against rather than
only fixtures.

Sequencing

Less open than it was. Steps 2–4 are where the old bag was most awkward —
listElementType holding a size, the record key confusion — and those are the
steps that no longer have a bag to be written against at all. Writing them once
against the DTO is now the only path, not the cheaper of two.

If anything in the DTO shape is awkward to render, now is the free time to change
it — it has no consumers.

[harshithmohan]

Follow-up to revam's comment above: two shape proposals from walking ServerSettings through the new DTO end-to-end, plus a few renderer-relevant findings

We took a live UiDefinition payload from a server running the PR branch, checked it against the actual configuration document for binding consistency, and traced the full render → bind → invoke flow. First, the current shape as shipped — since it's referenced below but not shown concretely anywhere in this discussion — then two proposed refinements and findings that touch this RFC's designs.

Current shape (as of PR 553db752)

The AniDB login area of CoreSettings, from the live payload (trimmed):

// GET /api/v3/Configuration/{configID}/UiDefinition
{
  "ID": "19c7a5e2-…",
  "Name": "Core Settings",
  "Root": {
    "Kind": "section-container",          // concrete discriminator — no more "auto"
    "SectionType": "tab",
    "DefaultSectionName": "Misc.",
    "AppendFloatingSectionsAtEnd": true,
    "ShowSaveAction": true,
    "Items": {                            // map keyed by document property name
      "Username": {
        "Kind": "string",
        "Key": "Username",
        "Label": "Username",
        "Description": "AniDB username.",
        "Size": "normal",
        "Visibility": { "Default": "visible", "Advanced": false, "Toggle": null, "Disable": null },
        "Badge": null,
        "RequiresRestart": false,
        "EnvironmentVariable": { "Name": "ANIDB_USER", "AllowOverride": false },
        "SectionName": "Login",           // ← grouping lives here today
        "Default": null,
        "IsRequired": false,
        "IsNullable": true,
        "DeniedValues": null
      },
      "Password": { "Kind": "password", "SectionName": "Login", "…": "…" },
      "MaxRelationDepth": {
        "Kind": "integer",
        "Minimum": 0, "Maximum": 5,       // constraints live ON the element now
        "Size": "small",
        "SectionName": "Download",
        "…": "…"
      },
      "MyList_StorageState": {
        "Kind": "enum",
        "Values": [                       // options pre-resolved — no schema round-trip
          { "Title": "Unknown", "Value": "Unknown" },
          { "Title": "HDD",     "Value": "HDD" }, …
        ],
        "SectionName": "MyList", "…": "…"
      }
      // nested objects inline as nested section-containers — no $refs to resolve
    },
    "Actions": {
      "Test": {
        "ID": "Test",
        "Title": "Test",
        "Theme": "primary",
        "Position": "start",
        "Size": "normal",
        "SectionName": "Login",
        "MemberName": "Test",
        "DisableIfNoChanges": false
      }
    },
    "Structure": [                        // authored order, interleaving fields & buttons
      { "Name": "Username", "Kind": "item" },
      { "Name": "Password", "Kind": "item" },
      { "Name": "Test",     "Kind": "action" },
      { "Name": "DownloadCharacters", "Kind": "item" },
      …
    ]
  },
  "Definitions": {}                       // only populated to break reference cycles
}

Each Kind value maps 1:1 to an element-type renderer, so DynamicField's dispatch becomes a switch on Kind; resolveSchemaRefs becomes unnecessary since $refs are already resolved or hoisted into Definitions.

Proposal A: replace flat Structure + per-element SectionName with grouped Sections

Revam's comment notes both maps enumerate in authored order and "Structure is for when you want the two interleaved." There's a third job hiding in there: grouping into tabs/sections currently has no home in the data — grouping lives as SectionName scattered across every element and action (see above) — so a client renders a tab by filtering every element on sectionName, at every container depth, on every render:

const fields = Object.values(root.items).filter(e => e.sectionName === activeTab);

Proposal: keep Items/Actions exactly as they are, but make grouping explicit (full proposal):

// Same Items/Actions as above — SectionName gone from elements and actions:
"Items": {
  "Username": { "Kind": "string", "…": "…" },
  "Password": { "Kind": "password", "…": "…" }
},
"Actions": {
  "Test": { "Name": "Test", "Position": "start", "Path": "AniDb", "…": "…" }
},
"Sections": [
  {
    "name": "Login",
    "members": [
      { "name": "Username", "kind": "item" },
      { "name": "Password", "kind": "item" },
      { "name": "Test",     "kind": "action" }   // button placement preserved
    ]
  },
  { "name": "Download", "members": [ … ] },
  …
]

Rendering a tab becomes sections.find(s => s.name === tab).members plus map lookups — no filtering, uniform for tabs/field-sets/minimal (a container with no [SectionName] anywhere just gets one synthesized section named after defaultSectionName). For this RFC that means DynamicSection receives its members pre-grouped instead of deriving groups itself, and section ordering (including AppendFloatingSectionsAtEnd) is server-decided rather than re-derived per client.

Proposal B: actions should carry their invocation path; rename ID → Name

This RFC's config-action-buttons design correctly describes POST Configuration/{id}/PerformAction?actionName={methodName}&path={path} — but neither input is fully available from the definition: path ("dotted ancestor-container keys," e.g. "AniDb" for the Test button) must be reconstructed from navigation state, and ID collides with standalone executable actions' GUID IDs while being sent as actionName. Proposal (detail): emit the resolved Path on each action (shown as "Path": "AniDb" above) and rename ID → Name. Then the RFC's "On click" handler needs zero out-of-band knowledge — config ID from the envelope, name + path from the action object.

Findings relevant to the renderers here

1. Correction to the comment above: UiSelectElement does not carry Options/Groups on the current branch (553db752) — it's only SelectType + MultipleItems. Options still live in the SelectComponent<T> value at the element's key path, server-populated (the offline-importer flow described is right about the mechanism). The select renderer needs to read options from the configuration document, and an unpopulated value means an empty dropdown — worth deciding whether that's acceptable or warrants a DependsOn-style field before building it.
2. Descriptions leak XML-doc whitespace and source-wrapping newlines (e.g. "The image source.\n ", "…it will use\nthe default location."). These are the tooltip/subtitle strings this RFC plans to render — flagged server-side (in this follow-up); if not fixed at the emitter, every consumer trims forever.
3. Visibility toggle resolution has two unspecified cases that directly affect the lodash-get approach proposed here: do conditions inside list items resolve per-item-instance or against the enclosing object, and are they evaluated against the client's unsaved edit state (presumably yes)? Both produce silently-wrong UI if a client guesses differently than the server intends — asked upstream, linking when answered.
4. Flag enums (enumIsFlag) have no write format. The checkbox-list treatment proposed for them needs to know how a combination serializes back (currently comma-separated names via the enum converters) — also asked upstream.
5. Validation errors correlate by document path ({ "AniDb.Username": […] } returned from Validate/save alike, always HTTP 200 inside ConfigurationActionResult) — match keys against the element Key-chain join and route unknown paths to a form-level error bucket.

[revam]

Update: the DTO shape changed after the review round

The feedback in this thread and on the PR landed, and the shape a renderer reads is meaningfully different from what I described above. The branch is rebased onto master and pushed, so a live payload from it reflects everything below.

Grouping is compiled on the server now, and positionally. A container files its members in three maps and puts them back in order with Structure, whose entries name which map to look in:

// GET /api/v3/Configuration/{configID}/UiDefinition  →  Root.Items.AniDb
{
  "Kind": "section-container",
  "SectionType": "minimal",
  "ShowSaveAction": false,
  "HasLiveEdit": false,
  "HasNestedLiveEdit": false,
  "Items":    { "Username": { … }, "Password": { … }, "AVDump": { … } },
  "Actions":  { "Test": { "Name": "Test", "Title": "Test", "Theme": "primary", … } },
  "FloatingSections": {
    "Login": {
      "Title": "Login",
      "Description": null,
      "HasNestedLiveEdit": false,
      "StartActions": ["Test"],
      "EndActions": [],
      "Structure": [ { "Name": "Username", "Kind": "item" },
                     { "Name": "Password", "Kind": "item" } ]
    }
  },
  "StartActions": [], "EndActions": [],
  "Structure": [ { "Name": "Login",    "Kind": "floating-section" },
                 { "Name": "Download", "Kind": "floating-section" },
                 { "Name": "MyList",   "Kind": "floating-section" } ]
}

So the render loop is: walk Structure, and for each entry index into Items, Actions or FloatingSections. A floating section has a structure of its own holding items and inline actions. Nothing is filtered, and nothing is grouped client-side.

What changed against what I described earlier:

• SectionName is gone from elements and actions, along with DefaultSectionName and AppendFloatingSectionsAtEnd on the container. The structure says what they said.
• Members render where they were authored. A nested class stays an item and labels itself, so it is not swept to one end; [SectionName] gathers members into a floating section entered at the first of them; anything unnamed stays in place. A tab container gathers what is left over, because a tab needs a label.
• Position is gone from the wire. A pinned button appears in StartActions or EndActions on whatever holds it, and a button attached to a field appears in that element's AttachedStartActions or AttachedEndActions.
• Conditions carry an operator. UiCondition has Operator and Values beside Value, covering Equals, NotEquals, IsEmpty, IsNotEmpty, In, NotIn, GreaterThan, LessThan, Contains. InverseCondition is gone, since every use of it was a negated operator. Treat an operator you do not know as unmet.
• Live edit is addressable. A container carries HasLiveEdit and HasNestedLiveEdit, a floating section carries HasNestedLiveEdit, and an element carries ReactsToLiveEdit, the events an edit to it is worth posting on. Empty means nothing watches it, so the form stays local.
• [DataType(DataType.Password)] renders as a password element, alongside [PasswordPropertyText]. Secret masking follows both now, so a field shown as stars is no longer serialized in the clear.

On @harshithmohan's follow-up

• Proposal A, grouped sections: adopted, with a different shape. Grouping is server-side, but positional rather than everything-into-groups, so authored order survives and a nested class is not hoisted out of the flow. The groups live in a FloatingSections map keyed by title rather than inline in the structure, so lookups match the pattern Items and Actions already set.
• Proposal B, split decision. ID is now Name, for exactly the reason given. Path is declined: a definition describes a type, not an instance, and the same container repeats as a list item or a record value where the path differs per row, so there is no single path to emit. Inside a list only the client knows the index anyway. The On click handler therefore keeps the container chain it descended through and sends that as path.
• Finding 1, select options live in the value: correct, and staying that way. The component owns its options; the definition describes the shape. What changes is that the client now knows when to refresh them, since ReactsToLiveEdit says which fields a handler watches. The intended authoring pattern is a scalar holding the choice plus a nullable SelectComponent populated in a Load or LiveEdit handler and nulled once chosen, or stripped in a Save handler, which keeps probe output out of settings-server.json. Written up in Shoko.Abstractions/UI/README.md on the branch. No DependsOn.
• Finding 2, description whitespace: fixed at the emitter. ServerSettings alone had 77 descriptions with a stray newline or an untrimmed end, and a test pins it. Nothing to trim client-side.
• Finding 3, condition resolution: specified. A condition resolves against the instance it sits in, so inside a list item it is per item. It evaluates against the client's current unsaved draft. It cannot climb out of its enclosing object, though it may descend into a nested class with a dotted path, and it never points through a list or dictionary. All three are in the XML docs now.
• Finding 4, flag enums: still open. enumIsFlag is no longer in the schema bag; IsFlag sits on the enum element instead. The write format is still unspecified, and I would rather pin it when something actually ships a flag enum than guess now.
• Finding 5, validation errors by document path: unchanged. Element keys are still the document property names, so the key-chain join is unaffected by the grouping rework.

For the RFC's build order, the practical differences are: section-container becomes one switch over three kinds rather than any grouping logic; the condition evaluator needs the operator set rather than equality plus a flag; and a form only needs to talk to the server while editing a branch whose flags say something reacts.

The PR description is updated to match, and three things are deliberately still open there: an element for a keyed set only the server can enumerate, an optional revision on the LiveEdit response, and how a flag enum serializes back.

[revam]

Follow-up to the update above: five more commits, and two of them contradict what I told you. Anyone building against the shape described in my previous comment should read this first.

1. A select's value is cased like everything else now. I said the lowercase field names were staying, on the grounds that they matched the schema's casing. They are gone: the definition carries the presentation now, so matching the schema bought nothing and left this one element's value as the exception a generic value binder gets wrong. The bound value reads:

"ManagedFolderSelector": {
  "Options": [
    { "Value": 1, "Label": "Anime", "GroupID": null, "IsSelected": true, "IsDefault": false, "IsDisabled": false }
  ],
  "Groups": []
}

So the binding layer needs no special case for it, which is the opposite of the warning in the RFC's select section.

2. auto no longer reaches you for a layout. The claim that the server resolves authored intent before serving only ever held for Kind. ListType and RecordType were still auto, which left you inferring flat versus complex from the item, which is the inference this whole document exists to remove. Both are resolved now, which needed a name for the plain layout, so flat exists on both. A list whose entry is a class of its own comes out complex-inline, a record's complex-dropdown, anything else flat, and a select is checkbox-list when it takes more than one value and flat-list otherwise. An authored layout is never overridden: a list of enums stays flat unless the class asked for enum-checkbox, so the shared checkbox sub-component the RFC plans is opt-in rather than inferred.

3. Rows can say what they are called. A class can hold a TitleComponent with Title and SubTitle, and the list points at it through ItemTitlePath and ItemCategoryPath. record gained those two paths as well, so a dictionary's values are labelled like a list's entries; both null means the entry is labelled by the key it is stored under. The [Key] fallback stays. This is the "what do we label a row with" gap under the complex list design.

4. Denied values now appear only where they can be applied. They used to be copied onto every element, including a select, whose options live in the value. A list or dictionary hoists them onto the entry, which is what an author denying values on a collection means, and a container, reference or select carries none. That settles the open question in the RFC's denied-values bullet: enum filtering is the only case, and nothing else will hand you values to filter.

5. Live edit answers two of the RFC's open edge cases. Every handler on the edited path runs now, innermost first, each handed what the one before it returned, with messages and validation errors collected across all of them and the document merged by construction. So a parent type does see an edit to a nested one. And a live edit naming a path that does not resolve is a no-op rather than a 400, which is the not-yet-added row case: treat reactive requests as best-effort. An explicitly invoked action is still strict.

Still open on the server side, unchanged: an element for a server-enumerated keyed set, the optional revision counter, and how a flag enum serialises back.

For what it is worth, we have an internal harness that renders a configuration from the definition alone, with no per-configuration code, and a test that walks a live Core Settings payload: every structure entry resolves, every member is listed exactly once, no layout says auto, every reference resolves, and no description carries documentation whitespace. It is a test harness for the server contract rather than a UI proposal, but it does say the document is walkable as served.

[revam]

A Concepts section for the RFC, as requested. This is meant to slot into the RFC after Summary and before Motivation, so a reader picks up the vocabulary before the argument for it. It describes the shape as of the current tip of ShokoAnime/ShokoServer#1414, including the two corrections in my previous comment. Copy it in as-is, or tell me what to change.

---

Concepts

Three documents are involved, and keeping them apart is most of understanding this.

Document	Endpoint	Describes	Changes when
Definition	GET Configuration/{id}/UiDefinition	The type: what fields exist, how they're laid out, what they're called	The plugin is updated
Values	GET Configuration/{id}	One instance: what this user has saved	The user saves
Schema	GET Configuration/{id}/Schema	The validation contract	The plugin is updated

A renderer needs the first two. The schema stays the authority for server-side validation, and a client built on the definition never has to read it.

Type, not instance. A definition is generated once per type, before anyone's saved document exists, so it cannot say how many rows a list has, what keys a dictionary holds, or where any particular row sits. Three consequences that come up repeatedly:

• An action carries no path to invoke it at, because the container holding it may repeat as a list row where the path differs per row. The client knows which row it's rendering, so the client builds the path.
• A condition's path is relative to the object its element sits in, never absolute, so the same condition means something different in each row.
• A list's item is described once, and that one description renders every row.

Element. The unit of the definition. Every element carries a Kind discriminator naming exactly one renderer, plus the same cross-cutting fields regardless of kind: label, description, size, visibility, badge, restart and environment indicators, denied values, default, required and nullable. A leaf element (string, integer, enum, …) binds to a value; a composite one (section-container, list, record) holds other elements.

Container and structure. A section-container files its members in three maps and puts them back in order with Structure:

Structure: [ {item}, {floating-section}, {item}, {action} ]
                │           │               │        │
     Items ◄────┘           │               └────────┤
     FloatingSections ◄─────┘                        │
     Actions ◄───────────────────────────────────────┘

Each entry names which map to look it up in, so resolving one is an index rather than a scan. Nothing is grouped, sorted or filtered client-side: the order in Structure is the order on screen.

Two kinds of grouping, which are easy to confuse:

• A nested class is an ordinary item whose element happens to be a container. It labels itself from its own label, and recursing into it is the same component one level down.
• A floating section is a group the server assembled out of members that share a [SectionName], plus a default section for whatever is left when the layout needs one. It has a title, an optional description, its own Structure, and its own pinned actions. It is not a member of anything; it is a view over members.

Action. A button the class declared. Where it renders is decided by which list names it, never by a property on the action: a container's or section's StartActions/EndActions for a pinned button, an element's AttachedStartActions/AttachedEndActions for one sitting on a field's row, or the structure itself for one inline among the fields. Invoking it needs the configuration id, the action's Name, and the path the client walked to reach it.

Live edit. A class can handle edits before anything is saved, to compute one field from another or fill a list of options. Because posting the whole document on every keystroke is not viable, the definition says where it is worth doing: a container carries HasLiveEdit and HasNestedLiveEdit, and an element carries ReactsToLiveEdit, the events an edit to that element is worth sending on. Empty means the form stays local.

What comes back is a result, not necessarily a document. It may carry JSON Patch operations against what was posted, and only does when the handler returned a configuration at all; it may instead, or additionally, carry messages to show, validation errors to attach to fields, a redirect, and flags such as whether to refresh. A handler that only validates, or only has something to say, returns no patch. The same result shape comes back from invoking an action, so one merge path covers both.

Condition. A comparison the client evaluates against the draft the user is editing, not the saved document. It carries a path, an operator, and a value or set of values. It can descend into a nested object and never climbs out of the one it is declared in. An operator a client does not recognise is treated as unmet.

Reference. Where the element tree would recurse into itself, the server emits a reference pointing into the definition's own Definitions table. It is the only place a client has to resolve anything by name.

Value binding. An element's key is the property name in the values document, so an element's path is the chain of keys walked to reach it. One exception worth knowing: a select element is deliberately thin, because its options live in the value it binds to rather than in the definition, populated by the server.

Who decides what.

Decision	Made by
Which fields exist, what they're called, how they're grouped and ordered	The plugin author, through attributes on the class
Turning that into elements, sections, layouts and flags	The server, once per type
Chrome: what a tab, a field set, a row or a button looks like	The client

[revam]

Update: options the server lists

The first open question from the PR, "an element for a keyed set only the server can enumerate", is answered in ShokoAnime/ShokoServer#1414. Here is what a renderer needs to know.

Authoring side. A method marked [OptionsProvider] names the members it lists options for:

[OptionsProvider(nameof(LibraryId), nameof(ExtraLibraryIds))]
public async Task<IReadOnlyList<SelectOption<int>>> ListLibraries(ILibraryService libraries)
    => (await libraries.GetAll()).Select(x => new SelectOption<int>(x.ID, x.Name)).ToList();

[OptionsProvider(nameof(ModeByPlugin), Target = OptionsTarget.Keys)]
public IEnumerable<SelectOption<Guid>> ListPlugins() => …;

• The default target, Values, means a scalar member itself, a list's entries, or a dictionary's values. Keys means a dictionary's keys. A dictionary's keys and values can each have their own provider, and a values provider can take the chosen key ([OptionsKey] Guid plugin) to narrow the values per key.
• The provider sees the draft with its unsaved edits, so options can depend on what the user just typed.
• Option types are primitives, enums, the usual text round-trip types (Guid, dates, TimeSpan, Uri) and any type that parses from text (IParsable<TSelf> or a [TypeConverter]).

On the wire.

• An element the server lists options for carries HasOptions: true, on the element that renders the choice: a scalar member, a list's Item, a dictionary's KeyItem (keys) or Item (values).
• There is one route per form: the client appends /Options to the form's own route, /api/v3/Configuration/{configID} for a configuration, or the route it invokes an executable action on (the ones under /api/v3/Action, not a configuration's custom actions), such as /api/v3/Series/1234/Action/{actionID}. The server sets that series, episode, group or file on the action for the provider to use.
• ?path= names the field getting the options: Library or Nested.Mode for a plain field, Tags for a list's entries, Mappings[2].Folder for a field inside a list entry (the provider runs on that entry). For a dictionary, ModeByPlugin asks for its keys and ModeByPlugin["<key>"] for the values of that key. The key need not be saved yet, so for a new entry the client picks the key first, then asks for that key's values.
• The body is the current draft for a configuration, or the parameters entered so far for an executable action.
• The answer is [{ "Value": …, "Label": "…" }], in the order the provider returned it. Value is serialised the way the member is. Label is always set: the provider's own label, else the enum member's name as the form already shows it, else the value as text.
• An empty list means "nothing to choose right now". A refusal comes back as the usual validation problem, keyed by member path (for example "set an API key first").

What the client should do.

• Fetch options when the element is shown, and again after an edit that could change them. The provider sees the draft, so the list can depend on other fields.
• Show stored values by the label of the matching option, not only inside the picker. For example, a dictionary keyed by plugin Guids should show plugin names. Fall back to the raw value when it isn't listed, such as an uninstalled plugin.
• There is no server-side search: a provider returns its full current list, and the client filters locally.
• An enum member with a provider narrows the enum: offer only the returned values, labelled as the static list would label them.

Also changed in this round. Actions attached to a member's row (AttachToMember, AttachedStartActions, AttachedEndActions) are gone. Configuration-level custom actions stay.

Test plugin. revam/dotnet-shoko-plugin-genui-test holds one configuration per level of reactivity (save only, conditions, custom actions, server options, live edit, lifecycle hooks, combined) and two executable actions, one global and one per series. Each member's description says what you should see, so it doubles as a checklist for the renderer. It is never released; build it against a checkout of the server branch with -p:ShokoRepositoryPath=… and drop it into a dev server's plugins folder.

[hidden4003]

Closing out the revision counter on live-edit responses

Hi @revam, this is one of the last items on the RFC's Open questions list, and I'd like to settle it one way or the other.

Where it appears in the RFC. The last bullet but two of "Open questions" says a monotonic revision counter for the live-edit/action-result response, so that a client can discard a stale, out-of-order reply, has been offered on the server side but not built. The Reactivity section describes the live-edit request and response, and says nothing about ordering.

What I understand the position to be. In your PR comment on 2026-09-18 you said a live edit persists nothing, so only the client that issued the request can change the draft. A debouncing client already knows the order it sent things in and can drop a response older than its newest in-flight one. You also said a server counter earns its place once something else can change the document mid-edit, and that nothing can today. You offered to add a monotonic revision, comparable within one session and one configuration, if we said the word. The narrowing from ReactiveMembers and Events also reduces how much can race.

Current state. I checked PR head 446e10f7c, and there's no revision field on the response or anywhere in the UI abstractions. So it's still offered and not built.

What I'm asking. Could you pick one of the following, so I can close the question in the next revision?

1. Implement it. The field is added to the response, and the RFC describes it as part of the live-edit and action-result envelope.
2. Propose an alternative. For example, a request identifier echoed back on the response, or something else you'd prefer.
3. Decline it. Ordering stays entirely on the client: the WebUI numbers its own live-edit requests and ignores any response older than the newest one it has applied.

If no option is chosen, the next revision of the RFC will record option 3 and remove this item from the open questions. The server-side counter stays available as an offer if a need for it appears later.

---

Update, 2026-10-11: Resolved with option 3, per the discussion on Discord. RFC v7 records the decision in the Reactivity section and no longer lists the counter among the open questions. No reply is needed here.

[revam]

ShokoAnime/ShokoServer#1414 is no longer a draft. If there's nothing else, it's ready to merge.