@owncast/plugin-sdk 0.1.0 → 0.3.0

package/README.md

@@ -2,19 +2,20 @@
 
 SDK for authoring [Owncast](https://owncast.online) plugins in JavaScript or TypeScript. Plugins compile to WebAssembly and run sandboxed inside the Owncast server.
 
-Most authors don't install this directly — instead, scaffold a new project with `npm create owncast-plugin <name>` and the generated `package.json` already lists it as a dependency.
+Most authors don't install this directly, instead, scaffold a new project with `npx create-owncast-plugin@latest <slug>` and the generated `package.json` already lists it as a dependency.
 
 ## Quick start
 
 ```sh
-npm create owncast-plugin my-plugin
+npx create-owncast-plugin@latest my-plugin
 cd my-plugin
-npm install   # postinstall fetches the per-platform wasm toolchain
-npm run build # bundles src/plugin.js → my-plugin.wasm + my-plugin.ocpkg
-npm test      # runs scenarios from __tests__/
+npm install     # postinstall fetches the per-platform wasm toolchain
+npm run build   # compiles src/plugin.js into an intermediate build artifact
+npm run package # zips manifest + wasm + assets + icon.png into my-plugin.ocpkg
+npm test        # runs scenarios from __tests__/
 ```
 
-Then drop `my-plugin.ocpkg` into your Owncast server's `plugins/` directory and enable it from the admin.
+Then install `my-plugin.ocpkg` in Owncast. From the admin's **Plugins** page click **Upload plugin** and pick the file, or copy it directly to the server's `data/plugins/` directory. Toggle **Enabled** on the plugin's row to load it.
 
 ## Writing a plugin
 
@@ -38,10 +39,11 @@ Declare the permissions your plugin uses (`chat.send` for the example above) in
 
 ## What's in the package
 
-- `index.js` — runtime: `definePlugin`, the `owncast.*` host wrappers, the `filter` constructor.
-- `index.d.ts` — TypeScript declarations for editor autocomplete on every event payload and host API.
-- `bin/owncast-plugin` — CLI: `build`, `test`, `serve`, `package` subcommands.
-- `scripts/postinstall.js` — downloads the per-platform wasm toolchain (`extism-js`, `wasm-merge`, `wasm-opt`) and the Go test/serve runner on install.
+- `index.js`, runtime: `definePlugin`, the `owncast.*` host wrappers, the `filter` constructor.
+- `index.d.ts`, TypeScript declarations for editor autocomplete on every event payload and host API.
+- `testing.js`, JS test API (`runScenarios`) for writing `__tests__/*.test.js` with the full ergonomics of JavaScript instead of static JSON.
+- `bin/owncast-plugin`, CLI: `build`, `test`, `serve`, `package` subcommands.
+- `scripts/postinstall.js`, downloads the per-platform wasm toolchain (`extism-js`, `wasm-merge`, `wasm-opt`) and the Go test/serve runner on install.
 
 ## License
 

package/bin/owncast-plugin.js

@@ -1,9 +1,15 @@
 #!/usr/bin/env node
-// `owncast-plugin build`   — bundle src/plugin.{js,ts} into <name>.wasm
-// `owncast-plugin test`    — run scenarios in __tests__/ against the wasm
-// `owncast-plugin serve`   — run a localhost dev HTTP server
-// `owncast-plugin package` — produce a single-file <name>.ocpkg suitable
+// `owncast-plugin build`  , bundle src/plugin.{js,ts} into <slug>.wasm
+// `owncast-plugin test`   , run scenarios in __tests__/ against the wasm
+// `owncast-plugin serve`  , run a localhost dev HTTP server
+// `owncast-plugin package`, produce a single-file <slug>.ocpkg suitable
 //                            for distribution / installation
+//
+// "Slug" is the plugin's identifier: lowercase, hyphenated, used in
+// filenames, URL segments, and as the registry's primary key. Plugin
+// authors set the human-readable display name via `name` in their
+// manifest; if they don't set `slug`, the CLI auto-derives it from
+// `name`.
 
 const fs = require("fs");
 const path = require("path");
@@ -14,24 +20,73 @@ const JSZip = require("jszip");
 const cmd = process.argv[2] || "build";
 const restArgs = process.argv.slice(3);
 
-if (cmd === "build") {
-  buildMain().catch(fail);
-} else if (cmd === "test") {
-  testMain(restArgs);
-} else if (cmd === "serve") {
-  serveMain(restArgs);
-} else if (cmd === "package") {
-  packageMain().catch(fail);
-} else {
-  console.error(`unknown command: ${cmd}\nusage: owncast-plugin <build|test|serve|package>`);
-  process.exit(1);
-}
-
 function fail(e) {
   console.error(`${cmd} failed: ${e.message}`);
   process.exit(1);
 }
 
+// slugPattern matches a valid plugin slug: a lowercase letter
+// followed by lowercase letters/digits/hyphens, up to 64 chars total.
+// Same shape the host + SDK + registry all validate against.
+const slugPattern = /^[a-z][a-z0-9-]{0,63}$/;
+
+// slugify mirrors the host's Go slugify: ASCII letters and digits
+// pass through lowercased; everything else collapses to a single
+// hyphen; leading and trailing hyphens are trimmed.
+// Non-ASCII names (e.g. "Café") degrade noisily (-> "caf"); plugins
+// with accented or non-Latin display names should pin `slug` in the
+// manifest instead of relying on auto-derivation.
+function slugify(input) {
+  let out = "";
+  let prevHyphen = false;
+  for (const ch of input) {
+    const code = ch.codePointAt(0);
+    let lower = ch;
+    if (code >= 65 && code <= 90) lower = String.fromCodePoint(code + 32);
+    const lc = lower.codePointAt(0);
+    if ((lc >= 97 && lc <= 122) || (lc >= 48 && lc <= 57)) {
+      out += lower;
+      prevHyphen = false;
+    } else if (!prevHyphen && out.length > 0) {
+      out += "-";
+      prevHyphen = true;
+    }
+  }
+  return out.replace(/-+$/, "");
+}
+
+// readAndResolveManifest loads plugin.manifest.json, validates the
+// required fields, and returns a manifest object with `slug` filled
+// in: either the author's explicit `slug`, or one auto-derived from
+// `name`. The returned object is what gets baked into MANIFEST_BASE
+// in the build's synthesized entry, so register() always emits both
+// name (display) and slug (identifier).
+function readAndResolveManifest(manifestPath) {
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+  if (!manifest.name || typeof manifest.name !== "string") {
+    throw new Error("manifest.name is required");
+  }
+  if (!manifest.version || typeof manifest.version !== "string") {
+    throw new Error("manifest.version is required");
+  }
+  let slug = manifest.slug;
+  if (!slug) {
+    slug = slugify(manifest.name);
+    if (!slug) {
+      throw new Error(
+        `could not derive a slug from manifest.name ${JSON.stringify(manifest.name)}; set manifest.slug explicitly`,
+      );
+    }
+  }
+  if (!slugPattern.test(slug)) {
+    throw new Error(
+      `manifest.slug ${JSON.stringify(slug)} must match ${slugPattern} (lowercase letters/digits/hyphens, starting with a letter, max 64 chars)`,
+    );
+  }
+  manifest.slug = slug;
+  return manifest;
+}
+
 function testMain(args) {
   runBinary("owncast-plugin-test", args);
 }
@@ -46,17 +101,20 @@ function runBinary(name, args) {
   if (!fs.existsSync(bin)) {
     console.error(
       `${name} not found at ${bin}\n` +
-      `In production this is fetched by the SDK postinstall. For the PoC, ` +
-      `build it via: cd owncast && go build -o tools/${name} ./cmd/${name}`
+        `In production this is fetched by the SDK postinstall. For the PoC, ` +
+        `build it via: cd owncast && go build -o tools/${name} ./cmd/${name}`,
     );
     process.exit(1);
   }
   const env = {
     ...process.env,
-    LD_LIBRARY_PATH: `${path.join(cache, "lib")}:${process.env.LD_LIBRARY_PATH || ""}`
+    LD_LIBRARY_PATH: `${path.join(cache, "lib")}:${process.env.LD_LIBRARY_PATH || ""}`,
   };
   try {
-    execFileSync(bin, args.length > 0 ? args : [process.cwd()], { stdio: "inherit", env });
+    execFileSync(bin, args.length > 0 ? args : [process.cwd()], {
+      stdio: "inherit",
+      env,
+    });
   } catch (e) {
     process.exit(typeof e.status === "number" ? e.status : 1);
   }
@@ -68,20 +126,27 @@ async function buildMain() {
   if (!fs.existsSync(manifestPath)) {
     throw new Error("plugin.manifest.json not found in current directory");
   }
-  const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
-  const name = manifest.name;
-  if (!name) throw new Error("manifest.name is required");
+  const manifest = readAndResolveManifest(manifestPath);
+  const slug = manifest.slug;
 
   // Detect entry point.
   let entry = null;
-  for (const candidate of ["src/plugin.ts", "src/plugin.js", "plugin.ts", "plugin.js"]) {
+  for (const candidate of [
+    "src/plugin.ts",
+    "src/plugin.js",
+    "plugin.ts",
+    "plugin.js",
+  ]) {
     const p = path.join(cwd, candidate);
     if (fs.existsSync(p)) {
       entry = p;
       break;
     }
   }
-  if (!entry) throw new Error("no plugin source found (expected src/plugin.ts or plugin.js)");
+  if (!entry)
+    throw new Error(
+      "no plugin source found (expected src/plugin.ts or plugin.js)",
+    );
 
   // Synthesize an entry that injects the manifest, requires user code,
   // then re-exports the SDK runtime exports as wasm-visible exports.
@@ -132,7 +197,7 @@ module.exports = { register, on_event, on_filter, on_http_request };
     platform: "neutral",
     target: "es2020",
     outfile: bundledJS,
-    logLevel: "warning"
+    logLevel: "warning",
   });
 
   // Generate index.d.ts declaring exports + host imports based on permissions.
@@ -143,16 +208,21 @@ module.exports = { register, on_event, on_filter, on_http_request };
   const cache = findCacheDir();
   const extismJs = path.join(cache, "extism-js");
   if (!fs.existsSync(extismJs)) {
-    throw new Error(`extism-js not found at ${extismJs} — run \`npm install\` to fetch the toolchain`);
+    throw new Error(
+      `extism-js not found at ${extismJs}, run \`npm install\` to fetch the toolchain`,
+    );
   }
   const env = {
     ...process.env,
     PATH: `${cache}:${process.env.PATH}`,
-    LD_LIBRARY_PATH: `${path.join(cache, "lib")}:${process.env.LD_LIBRARY_PATH || ""}`
+    LD_LIBRARY_PATH: `${path.join(cache, "lib")}:${process.env.LD_LIBRARY_PATH || ""}`,
   };
 
-  const wasmOut = path.join(cwd, `${name}.wasm`);
-  execFileSync(extismJs, [bundledJS, "-i", dts, "-o", wasmOut], { stdio: "inherit", env });
+  const wasmOut = path.join(cwd, `${slug}.wasm`);
+  execFileSync(extismJs, [bundledJS, "-i", dts, "-o", wasmOut], {
+    stdio: "inherit",
+    env,
+  });
 
   // If the project ships static assets in ./assets/, mirror them to the
   // canonical deployment layout (<name>-assets/) so plugin.Server finds them
@@ -160,17 +230,30 @@ module.exports = { register, on_event, on_filter, on_http_request };
   // show up live during dev (no rebuild needed for HTML/CSS changes).
   const assetsSrc = path.join(cwd, "assets");
   if (fs.existsSync(assetsSrc) && fs.statSync(assetsSrc).isDirectory()) {
-    const assetsDest = path.join(cwd, `${name}-assets`);
+    const assetsDest = path.join(cwd, `${slug}-assets`);
     let needsLink = true;
-    if (fs.existsSync(assetsDest)) {
-      try {
-        const st = fs.lstatSync(assetsDest);
-        if (st.isSymbolicLink() && fs.realpathSync(assetsDest) === fs.realpathSync(assetsSrc)) {
-          needsLink = false;
-        } else {
-          fs.rmSync(assetsDest, { recursive: true, force: true });
-        }
-      } catch {
+    // Use lstatSync (not existsSync), existsSync follows symlinks and
+    // returns false for a dangling link, but the link's inode is still
+    // there and would make symlinkSync below fail with EEXIST. lstatSync
+    // sees the link itself regardless of whether its target resolves.
+    let st;
+    try {
+      st = fs.lstatSync(assetsDest);
+    } catch {
+      // path doesn't exist at all, fall through to create it.
+    }
+    if (st) {
+      let target;
+      if (st.isSymbolicLink()) {
+        // realpathSync throws on dangling links; treat that as "doesn't
+        // match, replace it" rather than letting it abort the build.
+        try {
+          target = fs.realpathSync(assetsDest);
+        } catch {}
+      }
+      if (target && target === fs.realpathSync(assetsSrc)) {
+        needsLink = false;
+      } else {
         fs.rmSync(assetsDest, { recursive: true, force: true });
       }
     }
@@ -182,7 +265,7 @@ module.exports = { register, on_event, on_filter, on_http_request };
   console.log(`built ${path.relative(cwd, wasmOut)}`);
 }
 
-// `owncast-plugin package` — bundle the project into a single .ocpkg file
+// `owncast-plugin package`, bundle the project into a single .ocpkg file
 // (zip archive with plugin.manifest.json, plugin.wasm, and optional assets/).
 // Builds the wasm first if it doesn't exist.
 async function packageMain() {
@@ -191,11 +274,10 @@ async function packageMain() {
   if (!fs.existsSync(manifestPath)) {
     throw new Error("plugin.manifest.json not found in current directory");
   }
-  const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
-  const name = manifest.name;
-  if (!name) throw new Error("manifest.name is required");
+  const manifest = readAndResolveManifest(manifestPath);
+  const slug = manifest.slug;
 
-  const wasmPath = path.join(cwd, `${name}.wasm`);
+  const wasmPath = path.join(cwd, `${slug}.wasm`);
   if (!fs.existsSync(wasmPath)) {
     await buildMain();
   }
@@ -205,6 +287,15 @@ async function packageMain() {
   zip.file("plugin.manifest.json", fs.readFileSync(manifestPath));
   zip.file("plugin.wasm", fs.readFileSync(wasmPath));
   let fileCount = 2;
+  // Bundle a top-level icon.png if the plugin source root has one.
+  // The host reads it from /api/plugins/<slug>/icon to render in the
+  // admin list and sidebar (no manifest field, no http.serve
+  // permission required).
+  const iconPath = path.join(cwd, "icon.png");
+  if (fs.existsSync(iconPath) && fs.statSync(iconPath).isFile()) {
+    zip.file("icon.png", fs.readFileSync(iconPath));
+    fileCount++;
+  }
   if (fs.existsSync(assetsDir) && fs.statSync(assetsDir).isDirectory()) {
     for (const file of walkFiles(assetsDir)) {
       const rel = path.relative(assetsDir, file).split(path.sep).join("/");
@@ -213,15 +304,17 @@ async function packageMain() {
     }
   }
 
-  const outPath = path.join(cwd, `${name}.ocpkg`);
+  const outPath = path.join(cwd, `${slug}.ocpkg`);
   const buf = await zip.generateAsync({
     type: "nodebuffer",
     compression: "DEFLATE",
-    compressionOptions: { level: 6 }
+    compressionOptions: { level: 6 },
   });
   fs.writeFileSync(outPath, buf);
   const sizeKb = Math.round(fs.statSync(outPath).size / 1024);
-  console.log(`packaged ${path.relative(cwd, outPath)} (${sizeKb} KB, ${fileCount} files)`);
+  console.log(
+    `packaged ${path.relative(cwd, outPath)} (${sizeKb} KB, ${fileCount} files)`,
+  );
 }
 
 function* walkFiles(dir) {
@@ -248,7 +341,7 @@ function generateInterface(manifest) {
     "register(): I32",
     "on_event(): I32",
     "on_filter(): I32",
-    "on_http_request(): I32"
+    "on_http_request(): I32",
   ];
 
   const perms = new Set(manifest.permissions || []);
@@ -277,7 +370,9 @@ function generateInterface(manifest) {
     imports.push("owncast_user_get(idPtr: PTR): PTR");
   }
   if (perms.has("users.moderate")) {
-    imports.push("owncast_user_set_enabled(idPtr: PTR, enabled: I32, reasonPtr: PTR): void");
+    imports.push(
+      "owncast_user_set_enabled(idPtr: PTR, enabled: I32, reasonPtr: PTR): void",
+    );
     imports.push("owncast_ban_ip(ipPtr: PTR): void");
   }
   if (perms.has("storage.upload")) {
@@ -290,8 +385,14 @@ function generateInterface(manifest) {
     imports.push("owncast_kv_get(keyPtr: PTR): PTR");
     imports.push("owncast_kv_set(keyPtr: PTR, valPtr: PTR): void");
   }
-  if (perms.has("events.emit")) imports.push("owncast_emit_event(eventTypePtr: PTR, payloadPtr: PTR): void");
-  if (perms.has("http.sse")) imports.push("owncast_sse_send(channelPtr: PTR, eventPtr: PTR, dataPtr: PTR): void");
+  if (perms.has("events.emit"))
+    imports.push(
+      "owncast_emit_event(eventTypePtr: PTR, payloadPtr: PTR): void",
+    );
+  if (perms.has("http.sse"))
+    imports.push(
+      "owncast_sse_send(channelPtr: PTR, eventPtr: PTR, dataPtr: PTR): void",
+    );
   if (perms.has("server.read")) {
     imports.push("owncast_stream_current(): PTR");
     imports.push("owncast_server_info(): PTR");
@@ -306,6 +407,10 @@ function generateInterface(manifest) {
   if (perms.has("videoconfig.write")) {
     imports.push("owncast_video_config_write(configPtr: PTR): PTR");
   }
+  if (perms.has("ui.modify")) {
+    imports.push("owncast_add_actions(actionsPtr: PTR): void");
+    imports.push("owncast_clear_actions(): void");
+  }
 
   let out = `declare module 'main' {\n`;
   for (const e of exports) out += `  export function ${e};\n`;
@@ -326,9 +431,9 @@ function findCacheDir() {
   const candidates = [
     path.join(__dirname, ".cache"),
     path.join(__dirname, "..", "bin", ".cache"),
-    path.join(__dirname, "..", "..", "..", "tools")
+    path.join(__dirname, "..", "..", "..", "tools"),
   ];
-  // Pick the first candidate that has any of the expected tools — different
+  // Pick the first candidate that has any of the expected tools, different
   // commands need different binaries (build needs extism-js, test needs
   // owncast-plugin-test) but they share a cache.
   for (const c of candidates) {
@@ -343,3 +448,22 @@ function findCacheDir() {
   return candidates[0];
 }
 
+// Dispatch sits at the bottom so every const + function above is
+// fully initialized before any handler runs. Calling a handler from
+// the top of the file would put the top-level `const slugPattern`
+// (and friends) in the TDZ for the first synchronous slice of
+// buildMain/packageMain.
+if (cmd === "build") {
+  buildMain().catch(fail);
+} else if (cmd === "test") {
+  testMain(restArgs);
+} else if (cmd === "serve") {
+  serveMain(restArgs);
+} else if (cmd === "package") {
+  packageMain().catch(fail);
+} else {
+  console.error(
+    `unknown command: ${cmd}\nusage: owncast-plugin <build|test|serve|package>`,
+  );
+  process.exit(1);
+}

package/index.d.ts

@@ -6,7 +6,7 @@ export interface ChatMessage {
   timestamp: string;
 }
 
-/** A chat user — payload of join/part/rename events. */
+/** A chat user, payload of join/part/rename events. */
 export interface ChatUser {
   id: string;
   displayName: string;
@@ -15,13 +15,13 @@ export interface ChatUser {
   scopes?: string[];
 }
 
-/** Payload of `chat.user.renamed` — the same user changing their name. */
+/** Payload of `chat.user.renamed`, the same user changing their name. */
 export interface ChatUserRename {
   user: ChatUser;
   previousName: string;
 }
 
-/** Payload of `chat.message.moderated` — a message hidden/restored by a mod. */
+/** Payload of `chat.message.moderated`, a message hidden/restored by a mod. */
 export interface ChatMessageModeration {
   messageId: string;
   visible: boolean;
@@ -30,8 +30,8 @@ export interface ChatMessageModeration {
 
 /** Stream-lifecycle payloads. */
 export interface StreamLifecycleEvent {
-  startedAt?: string;     // ISO-8601, set for stream.started
-  stoppedAt?: string;     // ISO-8601, set for stream.stopped
+  startedAt?: string; // ISO-8601, set for stream.started
+  stoppedAt?: string; // ISO-8601, set for stream.stopped
   title?: string;
   summary?: string;
 }
@@ -125,7 +125,7 @@ export const Events: {
 /** Payload shape for fediverse engagement events. */
 export interface FediverseActor {
   name: string;
-  handle: string;      // e.g. "@alice@fediverse.example"
+  handle: string; // e.g. "@alice@fediverse.example"
   url?: string;
   image?: string;
 }
@@ -136,16 +136,16 @@ export interface FediverseEngagement {
   target?: { url: string };
 }
 
-/** Inbound fediverse post — a mention or reply that contains content the
+/** Inbound fediverse post, a mention or reply that contains content the
  *  plugin can act on. Carries both the rendered content (which has the
  *  source instance's HTML) and a plain-text version (HTML stripped). */
 export interface FediverseInboundPost {
   actor: FediverseActor;
-  content: string;                 // HTML from the source instance
-  contentText: string;             // HTML stripped to plain text
-  url: string;                     // permalink to the post on its source
-  postedAt: string;                // ISO-8601
-  inReplyTo?: string;              // parent post URL, when this is a reply
+  content: string; // HTML from the source instance
+  contentText: string; // HTML stripped to plain text
+  url: string; // permalink to the post on its source
+  postedAt: string; // ISO-8601
+  inReplyTo?: string; // parent post URL, when this is a reply
   attachments?: {
     url: string;
     mediaType: string;
@@ -158,6 +158,7 @@ export const Permissions: {
   readonly ChatSend: "chat.send";
   readonly ChatHistory: "chat.history";
   readonly ChatModerate: "chat.moderate";
+  readonly ChatFilter: "chat.filter";
   readonly StorageKV: "storage.kv";
   readonly StorageUpload: "storage.upload";
   readonly EventsEmit: "events.emit";
@@ -171,6 +172,7 @@ export const Permissions: {
   readonly HttpSSE: "http.sse";
   readonly VideoConfigRead: "videoconfig.read";
   readonly VideoConfigWrite: "videoconfig.write";
+  readonly UIModify: "ui.modify";
 };
 
 export interface BrowserPushPayload {
@@ -204,7 +206,7 @@ export interface User {
   displayName: string;
   previousNames?: string[];
   createdAt?: string;
-  disabledAt?: string;        // ISO-8601 if banned, omitted otherwise
+  disabledAt?: string; // ISO-8601 if banned, omitted otherwise
   scopes?: string[];
   isBot?: boolean;
   isAuthenticated?: boolean;
@@ -290,12 +292,12 @@ export interface PluginDef {
   onFediverseReply?(post: FediverseInboundPost): void | Promise<void>;
 
   /** HTTP request handler. Called for any path under /plugins/<name>/ that
-   *  isn't served as a static asset. Default-public — gate admin features
+   *  isn't served as a static asset. Default-public, gate admin features
    *  on `req.authenticated` yourself. Requires `http.serve` permission. */
   onHttpRequest?(req: IncomingHttpRequest): OutgoingHttpResponse;
 
   /** Handlers for plugin-emitted custom events. The key is the event type
-   *  string (e.g. "announcement.broadcast"). Notifications only — to filter
+   *  string (e.g. "announcement.broadcast"). Notifications only, to filter
    *  custom events, additional API will be needed. */
   on?: { [eventType: string]: (payload: any) => void | Promise<void> };
 
@@ -314,7 +316,7 @@ export const owncast: {
     send(text: string): void;
     /** Same identity, but in action style (italic, like IRC "/me"). */
     sendAction(text: string): void;
-    /** Post a system message — no user identity, rendered as a server
+    /** Post a system message, no user identity, rendered as a server
      *  announcement. The body is rendered as HTML, so the plugin is
      *  responsible for escaping any untrusted content. Same `chat.send`
      *  permission as the other send variants. */
@@ -348,11 +350,13 @@ export const owncast: {
     upload(name: string, data: Uint8Array | string): UploadResult | null;
   };
   /** Post to the fediverse on the streamer's behalf. Requires `fediverse.post`,
-   *  which is high-trust — admins should grant it sparingly. The host
-   *  rate-limits at ~5 posts/hour per plugin. */
+   *  which is high-trust (posts go out under the streamer's own handle);
+   *  admins should grant it sparingly. */
   fediverse: {
-    /** Publish a public, text-only post. Returns { url } on success or null
-     *  on rate-limit / disabled / other failure. */
+    /** Publish a public, text-only post. Returns `{ url }` (currently empty
+     *  on success: Owncast publishes the note but doesn't yet round-trip its
+     *  URL), or `null` when the host rejects the call (disabled, missing
+     *  permission, etc.). */
     post(text: string): { url: string } | null;
   };
   /** Send notifications via Owncast's configured channels.
@@ -372,6 +376,22 @@ export const owncast: {
   events: {
     emit(eventType: string, payload: unknown): void;
   };
+  /** Control over the viewer action buttons this plugin contributes.
+   *  The effective list shown to viewers is `manifest.actions` ++
+   *  whatever has been added at runtime via `add`. Requires
+   *  `ui.modify`. */
+  actions: {
+    /** Append one or more buttons to the plugin's runtime list. Each
+     *  entry is validated with the same rules as `manifest.actions`
+     *  (title required; exactly one of `url` or `html`; relative URLs
+     *  rewritten into this plugin's namespace; cross-plugin URLs
+     *  rejected). The next viewer `/api/config` request returns
+     *  `manifest.actions` ++ the runtime list. */
+    add(actions: ActionButton | ActionButton[]): void;
+    /** Drop the runtime additions; only `manifest.actions` remain on
+     *  the next viewer `/api/config` request. */
+    clear(): void;
+  };
   sse: {
     /** Push one Server-Sent-Event to every browser connected to this
      *  plugin's `/plugins/<name>/_sse/<channel>` stream. `event` is the SSE
@@ -416,7 +436,7 @@ export interface HttpResponse {
   body: string;
 }
 
-/** An entry in `manifest.actions` — declares an action button the Owncast
+/** An entry in `manifest.actions`, declares an action button the Owncast
  *  UI surfaces while this plugin is enabled. Mirrors Owncast's existing
  *  ExternalAction shape; the host merges enabled-plugin buttons with the
  *  admin-configured list.
@@ -429,7 +449,7 @@ export interface HttpResponse {
  *  explicit `/plugins/<your-name>/...` paths are accepted unchanged.
  *
  *  When the resolved URL points back into this plugin, the manifest must
- *  declare `http.serve` — the host rejects the load otherwise. */
+ *  declare `http.serve`, the host rejects the load otherwise. */
 export interface ActionButton {
   /** Button label. Required. */
   title: string;
@@ -437,7 +457,7 @@ export interface ActionButton {
   url?: string;
   /** Render this raw HTML when the button is pressed. Mutually exclusive with `url`. */
   html?: string;
-  /** Icon image URL — same path conventions as `url`. */
+  /** Icon image URL, same path conventions as `url`. */
   icon?: string;
   /** Accent color, e.g. "#3b82f6". */
   color?: string;
@@ -447,7 +467,7 @@ export interface ActionButton {
   openExternally?: boolean;
 }
 
-/** `manifest.network` — narrows outbound HTTP scope for plugins that
+/** `manifest.network`, narrows outbound HTTP scope for plugins that
  *  declare the `network.fetch` permission. Required when that permission
  *  is granted; the host rejects loads otherwise. */
 export interface NetworkConfig {