feat(plugins): support dynamic templated content in the UI for plugins

Author: gabek

docs/PLUGIN_AUTHOR_GUIDE.md

@@ -699,11 +699,11 @@ A common pattern is an admin page that lets the streamer add a custom button (la
 
 Three manifest fields let a plugin contribute content directly to the viewer page: CSS, JavaScript, and a block of HTML. The host inlines plugin contributions into the same response slots Owncast already uses for the admin's custom CSS, custom JS, and extra page content, so a viewer loads one stylesheet, one script, and one extra-content block regardless of how many plugins contributed.
 
-| Manifest field     | Inlined into                          | Required permission | Extension |
-| ------------------ | ------------------------------------- | ------------------- | --------- |
-| `styles`           | `/api/config` → `customStyles`        | `ui.modify`         | `.css`    |
-| `scripts`          | `/customjavascript`                   | `ui.modify`         | `.js`     |
-| `extraPageContent` | `/api/config` → `extraPageContent`    | `ui.modify`         | `.html`   |
+| Manifest field     | Inlined into                          | Required permission | Notes              |
+| ------------------ | ------------------------------------- | ------------------- | ------------------ |
+| `styles`           | `/api/config` → `customStyles`        | `ui.modify`         | must end `.css`    |
+| `scripts`          | `/customjavascript`                   | `ui.modify`         | must end `.js`     |
+| `extraPageContent` | `/api/config` → `extraPageContent`    | `ui.modify`         | static or dynamic  |
 
 ### Stylesheets
 
@@ -742,44 +742,72 @@ Two things to keep in mind about execution:
 
 ### Extra page content
 
+`extraPageContent` is an object with a required `slug` and an optional `content` file:
+
 ```json
 {
   "permissions": ["ui.modify"],
-  "extraPageContent": "content.html"
+  "extraPageContent": { "slug": "banner", "content": "content.html" }
 }
 ```
 
-One HTML file inlined at the top of the viewer's extra-content block, above whatever the admin has configured. Wrapped with `<!-- plugin: <slug> — <file> -->` for attribution. Path rules match `styles` and `scripts` but the entry has to end in `.html`. `http.serve` is not required because the HTML is folded into the `/api/config` response, not served as a URL.
+**Static** (`content` present): the host reads the file from `assets/` and inlines it at the top of the viewer's extra-content block, above whatever the admin has configured. Path rules match `styles` and `scripts` but the entry has to end in `.html`. `http.serve` is not required.
+
+**Dynamic** (`content` absent): the host calls `onPageContent({ slug, user? })` at `/api/config` time and inlines the returned HTML string. `user` is the requesting viewer's chat identity when available.
 
-The admin's extra page content goes through the markdown processor; plugin HTML does not (the host renders the admin's markdown first, then prepends your raw bytes). Tags and attributes pass through as written, so escape any untrusted strings you embed.
+```js
+module.exports = definePlugin({
+  onPageContent({ slug, user }) {
+    if (slug === "banner") {
+      const name = user?.displayName ?? "visitor";
+      return `<aside>Welcome, ${name}!</aside>`;
+    }
+    return "";
+  },
+});
+```
 
-A combined plugin shipping all three fields is the common pattern when you need behavior and presentation together (the `viewer-gate` example in the SDK pairs a CSS file with a JavaScript file; `page-content-demo` ships a single HTML block).
+The admin's extra page content goes through the markdown processor; plugin HTML does not. Tags and attributes pass through as written — escape any untrusted strings you embed.
 
 ## Viewer-page tabs
 
-Plugins can add tabs to the viewer page's tab row (alongside the built-in **About** and **Followers** tabs) with `manifest.tabs[]`. Each entry has a `title` and a `content` path to an HTML file under `assets/`:
+Plugins can add tabs to the viewer page's tab row (alongside the built-in **About** and **Followers** tabs) with `manifest.tabs[]`. Each entry requires a `title` and a `slug`; `content` is optional:
 
 ```json
 {
   "permissions": ["ui.modify"],
   "tabs": [
-    { "title": "Music", "content": "music.html" },
-    { "title": "Schedule", "content": "schedule.html" }
+    { "title": "Music",       "slug": "music",       "content": "music.html" },
+    { "title": "Stream Info", "slug": "stream-info" }
   ]
 }
 ```
 
-Requires `ui.modify`. `http.serve` is **not** required: each tab's HTML is read from `assets/` and inlined into the `pluginTabs[]` array on `/api/config`. The viewer page renders one AntD tab per entry with the title as the label and the inlined HTML as the body.
+- `slug` — required. Stable identifier, unique within the plugin's tabs. Passed to `onTabContent` so the handler knows which tab to render. Lowercase letters, digits, hyphens.
+- `title` — required. The label shown on the tab. Keep it short (~16 characters max for mobile).
+- `content` — optional. Relative path to a static HTML file in `assets/`. When omitted, the host calls `onTabContent`.
+
+**Static** (`content` present): the host reads the file from `assets/` and inlines it as the tab body. Path rules match `extraPageContent.content`.
 
-Per-entry rules (`content`):
+**Dynamic** (`content` absent): the host calls `onTabContent({ slug, user? })` and inlines the returned HTML string.
 
-- Bare paths auto-prefix to the plugin's namespace (`"music.html"` → `/plugins/<slug>/music.html`).
-- Fully qualified `/plugins/<slug>/...` paths pass through.
-- Paths in another plugin's namespace, `http(s)://` URLs, or non-`.html` extensions are rejected at load.
+```js
+module.exports = definePlugin({
+  onTabContent({ slug, user }) {
+    if (slug === "stream-info") {
+      const stream = owncast.stream.current();
+      return stream.online
+        ? `<p>Live: ${stream.title} — ${stream.viewers} viewers</p>`
+        : `<p>Offline</p>`;
+    }
+    return "";
+  },
+});
+```
 
-Tab keys are derived from the plugin's slug so a tab only unmounts when the plugin is disabled/removed, not on every render. Plugin tabs appear after the built-ins in the declaration order. Keep titles short — anything past ~16 characters won't render cleanly on mobile.
+Requires `ui.modify`. `http.serve` is not required — the host inlines the result, nothing is served at a URL. Add whatever data permissions (`server.read`, `chat.history`, etc.) your handler actually calls.
 
-The `tabs-demo` example in the SDK ships two minimal tabs (Music, Schedule) and is the recommended starting point.
+The `tabs-demo` example ships two static tabs; `page-content-demo` demonstrates dynamic rendering with Mustache templates and `server.read` data.
 
 ## Plugin-to-plugin events
 
@@ -838,7 +866,38 @@ Point your `test` script at that one entry (`node __tests__/index.test.js`) inst
 
 - `event: "<type>"`, fire-and-forget notification dispatch
 - `filter: "<type>"`, filter chain; inline `expect: {action, payload?, reason?}` checks the FilterResult
-- `http: { method, path, headers?, body?, expect: {status, headers?, body?} }`, sends an HTTP request through your plugin server
+- `http: { method, path, headers?, body?, user?, authenticated?, expect: {status, headers?, body?, bodyContains?} }`, sends an HTTP request through your plugin server
+- `tabContent: { slug, user?, expect: {body?, bodyContains?} }`, calls `onTabContent` directly and asserts on the returned HTML
+- `pageContent: { slug, user?, expect: {body?, bodyContains?} }`, calls `onPageContent` directly and asserts on the returned HTML
+
+```json
+[
+  {
+    "name": "stream-info tab renders live title",
+    "given": { "stream": { "online": true, "title": "Friday Night", "viewers": 12 } },
+    "events": [
+      {
+        "tabContent": {
+          "slug": "stream-info",
+          "expect": { "bodyContains": "Friday Night" }
+        }
+      }
+    ]
+  },
+  {
+    "name": "banner greets authenticated viewer by name",
+    "events": [
+      {
+        "pageContent": {
+          "slug": "banner",
+          "user": { "id": "u1", "displayName": "Alice" },
+          "expect": { "bodyContains": "Alice" }
+        }
+      }
+    ]
+  }
+]
+```
 
 ### Assertions
 

docs/WIRE_PROTOCOL.md

@@ -8,16 +8,18 @@ A plugin is a WebAssembly module exposing four well-known exports and (condition
 
 ## Exports (plugin → host)
 
-Every plugin must export these four functions:
+Every plugin must export these functions:
 
 | Function          | Input                      | Output                      | Purpose                                                                                               |
 | ----------------- | -------------------------- | --------------------------- | ----------------------------------------------------------------------------------------------------- |
 | `register`        | none                       | JSON `Manifest`             | Returns the plugin's subscriptions for the host to compare against the static `plugin.manifest.json`. |
 | `on_event`        | JSON `Envelope`            | none                        | Notification dispatch. Fire-and-forget.                                                               |
 | `on_filter`       | JSON `Envelope`            | JSON `FilterResult`         | Filter chain entry point.                                                                             |
 | `on_http_request` | JSON `IncomingHttpRequest` | JSON `OutgoingHttpResponse` | HTTP request handler for `/plugins/<name>/*`.                                                         |
+| `on_tab_content`  | JSON `ContentRequest`      | raw HTML string             | Render HTML for a dynamic tab (one without a static `content` file in the manifest).                 |
+| `on_page_content` | JSON `ContentRequest`      | raw HTML string             | Render HTML for a dynamic `extraPageContent` slot (one without a static `content` file).             |
 
-Each entry point has a per-call timeout enforced by the host. See the host's `dispatcher.go` and `server.go` for current values.
+`ContentRequest` shape: `{ "slug": "<tab-or-slot-slug>", "user"?: ChatUser }`. The host calls the appropriate export when building the `/api/config` response; the returned string is inlined directly as the body. An empty string is valid (renders nothing). Each entry point has a per-call timeout enforced by the host. See the host's `dispatcher.go` and `server.go` for current values.
 
 ## Imports (host → plugin)
 
@@ -133,6 +135,7 @@ These imports are granted to every plugin without a declared permission. A plugi
 - `owncast_timer_set(id: I64, delayMs: I64, repeat: I32): I32`, schedule a host-driven timer; the host fires the `timer.fire` event (payload `{id}`) when it elapses. Returns 1 on success, 0 if the plugin is at its pending-timer cap. `delayMs` is clamped to `[100, 86_400_000]`. The SDK maps `id`→callback for `owncast.timer.setTimeout/setInterval`.
 - `owncast_timer_clear(id: I64): void`, cancel a pending timer by id.
 - `owncast_config_get(keyPtr: PTR): PTR`, returns the JSON value of a `manifest.config` key (admin override, else declared default), or 0-offset for an unknown/unset key.
+- `owncast_asset_read(pathPtr: PTR): PTR`, returns the raw bytes of a file from the plugin's own `assets/` directory, or 0-offset when the file is missing or the path escapes the directory. The path is relative to `assets/` and must not start with `/` or contain `..` segments; the host rejects any path that would escape the plugin's own asset tree. Plugins use this to load bundled resources (templates, data files) at request time without needing `storage.fs`.
 
 The host also dispatches a `tick` event (payload `{now}`, host wall-clock ms) about once a second to any plugin defining `onTick`, independent of timers.
 
@@ -229,35 +232,53 @@ Same per-entry rules as `manifest.styles[]`, applied to `.js` files (only `ui.mo
 
 ### `manifest.extraPageContent`
 
-A single relative path to an HTML file the plugin contributes to the viewer's extra-content block. The host reads the file's bytes and prepends them to the admin's rendered `extraPageContent` on `/api/config`, so plugin HTML lands above the admin's prose.
+An object the plugin contributes to the viewer's extra-content block. The host prepends the resolved HTML to the admin's rendered `extraPageContent` on `/api/config`, so plugin HTML lands above the admin's prose.
 
-Per-entry validation:
+```json
+{
+  "slug": "string (required, identifies the slot — passed to on_page_content)",
+  "content": "string (optional, relative path to assets/<file>.html)"
+}
+```
+
+Validation:
 
 - `ui.modify` permission required.
 - `http.serve` is **not** required: the HTML is inlined into the API response, not served at a URL.
-- Same path-shape rules as `manifest.styles[]`, applied to a single `.html` entry.
+- `slug` must be a valid slug (lowercase letters/digits/hyphens, starting with a letter, max 64 chars).
+- When `content` is present, the same path-shape rules as `manifest.styles[]` apply (must end in `.html`).
+
+**Static** (`content` present): the host reads the file from `assets/` and inlines its bytes.
+
+**Dynamic** (`content` absent): the host calls `on_page_content` with `{ slug, user? }` and inlines the returned HTML string. `user` carries the requesting viewer's chat identity when available.
 
 Each contribution is wrapped with an `<!-- plugin: <slug> — <file> -->\n` comment for in-page attribution. The admin's content goes through the markdown processor before plugin HTML is prepended; plugin HTML is left raw so tags and attributes pass through as written.
 
 ### `manifest.tabs[]`
 
-An array of viewer-page tabs the plugin contributes alongside the built-in tabs (Followers, About). Each entry's `content` is a relative path to an HTML file the host reads from the plugin's assets/ directory at request time.
+An array of viewer-page tabs the plugin contributes alongside the built-in tabs (Followers, About).
 
 ```json
 {
-  "title": "string (required)",
-  "content": "string (required, relative path to assets/<file>.html)"
+  "title": "string (required, tab label)",
+  "slug": "string (required, stable identifier — passed to on_tab_content)",
+  "content": "string (optional, relative path to assets/<file>.html)"
 }
 ```
 
-Per-entry validation:
+Validation:
 
 - `ui.modify` permission required.
 - `http.serve` is **not** required: each tab's HTML is inlined into the response, not served at a URL.
-- Title must be non-empty.
-- `content` path follows the same rules as `manifest.extraPageContent` (auto-prefix to the plugin's namespace, cross-plugin paths and `http(s)://` URLs rejected, must end in `.html`).
+- `title` must be non-empty. Unique within the plugin's tabs.
+- `slug` must be a valid slug. Unique within the plugin's tabs. Passed to `on_tab_content` so the plugin knows which tab to render.
+- When `content` is present, the same path rules as `manifest.extraPageContent.content` apply (must end in `.html`).
+
+**Static** (`content` present): the host reads the file from `assets/` and inlines its bytes.
+
+**Dynamic** (`content` absent): the host calls `on_tab_content` with `{ slug, user? }` and inlines the returned HTML string.
 
-The host emits the tab list on `GET /api/config` under `pluginTabs[]` as `[{slug, title, html}]` entries. The viewer page maps each entry to a tab whose body renders the inlined HTML. Slug doubles as the React key so a tab only unmounts when the source plugin is disabled/removed.
+The host emits the tab list on `GET /api/config` under `pluginTabs[]` as `[{slug, title, html}]` entries. The viewer page maps each entry to a tab whose body renders the inlined HTML. `slug` doubles as the React key so a tab only unmounts when the source plugin is disabled/removed.
 
 ## Payload types
 
@@ -269,7 +290,7 @@ Each language SDK is responsible for:
 
 - Declaring the imports listed above (gated by manifest permissions) so the plugin author's call into `owncast.chat.send(...)` resolves to the right wasm import.
 - Encoding/decoding payloads as JSON or text per the table above.
-- Implementing the four exports' dispatch loop: parse the envelope, route to the right handler, serialize the response.
+- Implementing the exports' dispatch loop: parse the envelope, route to the right handler, serialize the response. This covers all six exports: `register`, `on_event`, `on_filter`, `on_http_request`, `on_tab_content`, and `on_page_content`.
 
 The Owncast server repo's plugin runtime is responsible for:
 

examples/js/page-content-demo/INSTRUCTIONS.md

@@ -1,34 +1,56 @@
 # Page Content Demo
 
-Smallest possible example of the `manifest.extraPageContent` capability. The plugin ships a single HTML file and the host inlines its bytes at the top of the viewer page's extra-content block.
+Demonstrates dynamic viewer page content rendered server-side with Mustache. The plugin contributes a personalised banner above the tab row and a live "Stream Info" tab — both rendered at request time with no static HTML files or client-side fetch calls.
 
 ## What you'll see when enabled
 
-An amber-bordered banner appears at the top of the viewer page's extra-content block reading:
+**Banner (extra page content):** An amber-bordered panel at the top of the viewer page's extra-content block greeting the viewer by their chat display name. Anonymous viewers see "visitor".
 
-> page-content-demo: HTML reached the viewer page's extra-content block.
-
-The contribution lands above whatever the admin has written into the extra page content field, so any page content the admin has configured continues to render unchanged underneath.
+**Stream Info tab:** A new tab in the viewer tab row showing live stream state (online/offline, title, viewer count, started time), server metadata (name, version, URL), tags, social handles, and federation status — all rendered from `owncast.stream.current()` and related APIs.
 
 ## How it works
 
-The manifest declares a single HTML asset:
+The manifest declares the two slots without `content` paths, which tells the host to call the plugin's handlers instead of reading static files:
 
 ```json
 {
-  "permissions": ["ui.modify"],
-  "extraPageContent": "content.html"
+  "permissions": ["ui.modify", "server.read"],
+  "extraPageContent": { "slug": "banner" },
+  "tabs": [
+    { "title": "Stream Info", "slug": "stream-info" }
+  ]
 }
 ```
 
-The host rewrites the bare path to `/plugins/page-content-demo/content.html` (the canonical form), reads the file's bytes from the plugin, and prepends them to the admin's rendered `extraPageContent` on `/api/config`. Each contribution is wrapped with an `<!-- plugin: <slug> ... -->` comment so a reader can attribute the markup back to the plugin that shipped it.
+When Owncast builds its `/api/config` response it calls:
+
+- `onPageContent({ slug: "banner", user? })` to get the banner HTML
+- `onTabContent({ slug: "stream-info", user? })` to get the tab HTML
+
+Both handlers load their Mustache template from `assets/` via `owncast.assets.readText(name)` and render it with the relevant data.
+
+## Templates
+
+- `assets/greeting.mustache` — the banner; uses `{{displayName}}` with Mustache's auto-escaping.
+- `assets/info.mustache` — the stream info tab; uses `{{#stream.online}}` / `{{^stream.online}}` conditionals and `{{#tags}}{{.}}{{/tags}}` iteration.
 
 ## Permissions
 
-- **ui.modify** — the plugin paints inside Owncast's chrome.
+- **ui.modify** — required for `extraPageContent` and `tabs`.
+- **server.read** — required by `onTabContent` to call `owncast.stream.current()`, `owncast.server.info()`, etc.
 
-`http.serve` is not required because the HTML is inlined into the `/api/config` response, not served as a URL.
+`http.serve` is not needed. The host calls the handlers directly and inlines the returned HTML; there are no plugin HTTP endpoints.
 
-## When to use this as a template
+## Testing
 
-Start here if you want to ship inline HTML for the viewer page: a sponsor banner, an announcement strip, a static call-to-action. Plugin HTML doesn't go through the markdown processor, so HTML tags and attributes pass through unmodified.
+Scenarios in `__tests__/` use the `pageContent` and `tabContent` step types to exercise the handlers directly:
+
+```json
+{
+  "pageContent": {
+    "slug": "banner",
+    "user": { "id": "u-alice", "displayName": "Alice" },
+    "expect": { "bodyContains": "Alice" }
+  }
+}
+```