UI extensions

The rule#

A plugin ships no Angular. It declares data in its manifest's ui.* block; core renders it with its own, existing components. If a settings page needs something none of the three page kinds below can express, it isn't a plugin page, the answer is a core change adding a new kind, not a plugin shipping code. This is deliberately restrictive: it's what lets every plugin's admin surface look and behave consistently, and what lets core keep rendering an old plugin's declared UI correctly across a client release.

ui.contributions[]#

One entry per nav item, menu row, or settings-sidebar link.

The six slots#

A route contribution opening one of your own views must be exactly /plugins/<your-id>/<pageId> or /admin/settings/plugins/<your-id>/<pageId>, where <pageId> is a page you declare in ui.configPages; anything else fails registration (invalid-ui-contribution). Declaring a page does not link to it: only a settings.page contribution actually puts it in the sidebar.

The when predicate vocabulary#

Evaluated with .every(), entirely client-side, from state the client already has, nothing is re-fetched to answer a when. A leading ! negates. An unrecognised predicate always evaluates false, negated or not, so a client that doesn't understand a rule hides the row instead of guessing.

None of this is a trust boundary: whatever a when hides, the route behind it is still checked server-side with the same CASL policy as ever. A plugin row that reuses a core actionId inherits that core action's own guards too, a plugin can narrow a core action, never widen it.

actionId, per slot: also a closed vocabulary#

An action.kind: 'action' row names an id core implements; an id core doesn't recognise, or that the current surface has no handler for, makes the row disappear rather than render inert.

ui.configPages[]#

One entry per settings page, discriminated on kind. Missing kind means form.

form (the default, and the only kind that works with the process stopped)#

Rendered by a generic schema-form component. fields is an ordered array of items:

min/max (numbers) and minLength/maxLength (everything else) are the only validation a field may declare, enforced by the renderer before it saves. There's deliberately no author-supplied regular expression: a pattern from an untrusted manifest, or from a providers page's fields arriving over HTTP at render time, has no syntactic check that separates a safe expression from one that hangs the tab. A blank required field is shown as a hint but never blocks saving, clearing a value is how an operator unsets it.

Secrets. secret: true on a field means: stripped from every read response, and only written back when the incoming value is non-empty. A resource that honours this lists which of its secret keys currently hold a value under the response key secretsSet (SECRETS_SET_KEY in the contract); the editor then shows those masked, with an option to erase (write null) rather than ask the operator to retype a credential it never received. A blank field on save means "leave it alone", not "clear it", clearing needs the explicit erase.

actions[] on a form page ({ id, labelKey, actionId }) renders outline buttons beside Save, restricted to the closed actionId set above, today just events.test-delivery.

providers#

A CRUD list of instances (indexers, download clients, notification targets) over the plugin's own routes. Needs the process running.

table#

A read-only list over one route, with declared columns and row/list actions. Needs the process running.

ui.releasePicker#

"releasePicker": {
  "movie":   { "search": "/:id/releases",                       "grab": "/:id/grab" },
  "season":  { "search": "/:id/seasons/:seasonId/releases",      "grab": "/:id/seasons/:seasonId/grab" },
  "episode": { "search": "/:id/episodes/:episodeId/releases",    "grab": "/:id/episodes/:episodeId/grab" }
}

Every route named here must also appear in this manifest's own routes[], search as GET, grab as POST, so it carries a policy like any other. If more than one installed plugin declares releasePicker, the lexicographically smallest plugin id wins; the rest are logged and ignored. Only the winner's declaration is served from GET /plugins/ui.

ui.player#

"player": { "preRollRoute": "/pre-roll" }

One route, which must be a declared POST entry in this manifest's own routes[]. Before a playback-info response goes out, core POSTs { mediaFileId, mediaId, episodeId } to the winning plugin's route (same lexicographic tie-break as the release picker) and expects a JSON array of { mediaFileId, labelKey?, skippable? }, an id, never a URL or a path. The array is capped at 5 items; anything past the cap, a non-positive-integer id, a repeat, or the item about to play anyway is dropped. Every id core gets back is still resolved and ACL-checked through the exact path the main item uses, a plugin can only name a candidate, never grant access to one. If nothing answers in time, or answers anything other than exactly this shape, playback-info simply omits preRoll, the feature is invisible on failure, never a broken call. The Apple TV and Cast players don't model this field at all and only ever play the main item.

How each slot actually renders#

There's no generic "plugin slot" component; each slot is merged into an existing one, sorted by weight alongside core's own entries in the same slot:

i18n#

Same rules as the manifest reference: one shared root per plugin, first plugin loaded keeps it, a conflicting second plugin fails registration with i18n-namespace-conflict rather than silently losing its strings.