This page is written to be enough on its own, also for an AI agent that gets only this link (the raw Markdown version ends in index.md). It covers two kinds of plugins; pick one:
| HTML widget plugin | Standalone plugin (WebAssembly) | |
|---|---|---|
| What it is | a folder with plugin.json and a web page | one .wasm file, runs inside the app |
| Language | HTML, JS, CSS (any web stack) | Go (SDK provided); Rust and others through the ABI |
| Runs | in a sandboxed iframe of the overlay | on the server, no window |
| Good for | what is drawn on the stream: chat, counters, alerts | logic that must keep running: Twitch rewards, queues, timers, HTTP calls, bot messages, events |
| Can have a UI | it is the UI | yes: widgets and a settings page packed into the same file |
They combine: a standalone plugin can ship its own widgets, and a widget talks to its plugin through oc.plugin.
Part 1. HTML widget plugin
Folder
plugins/
my-widget/
plugin.json
index.html
app.js
The plugins folder is opened from Add Source → Open plugins folder. The widget is served at /plugins/<id>/.
plugin.json
{
"id": "my-widget",
"name": "My widget",
"version": "1.0.0",
"description": "What the widget does",
"entry": "index.html",
"defaultSize": { "width": 480, "height": 200 },
"permissions": ["chat.read", "storage"],
"settings": [
{ "key": "channel", "label": "Channel", "type": "string", "default": "" },
{ "key": "size", "label": "Font size", "type": "number", "default": 32, "min": 8, "max": 200 },
{ "key": "color", "label": "Color", "type": "color", "default": "#ffffff" },
{ "key": "mode", "label": "Mode", "type": "select", "default": "a",
"options": [ { "value": "a", "label": "Mode A" }, { "value": "b", "label": "Mode B" } ] }
]
}
id:a-z A-Z 0-9 _ -, up to 64 characters, equal to the folder name.version: semver, raise it on every change (updates are offered by version).entry: the page opened at/plugins/<id>/(defaultindex.html).- Setting types:
string,text,number,range,bool,color(#rrggbb),font,select(needsoptions).min,max,stepfornumberandrange;grouptitles a section;helpis a caption. - The editor stores only values the user changed, so the widget must know the defaults too. Keep them equal to the manifest.
- Settings reach the widget as query parameters of its address:
?size=32&color=%23ffffff. Numbers are32, booleanstrueorfalse.
index.html
<!doctype html>
<meta charset="utf-8">
<style>body { margin: 0; background: transparent; color: #fff; font: 32px sans-serif; }</style>
<div id="out"></div>
<script src="/plugin-sdk/oc.js"></script>
<script>
const size = oc.param("size", 32); // reads the query, cast to the type of the default
document.body.style.fontSize = size + "px";
oc.chat.on("message", (m) => {
document.getElementById("out").textContent = m.displayName + ": " + m.text;
});
oc.chat.subscribe(); // chat of the streamer's channel
</script>
The page background must be transparent: it is drawn over the stream. oc.js gives the global oc. The complete typed API is one file, oc.d.ts, served by a running app at /plugin-sdk/oc.d.ts (and in the repository at web/sdk/oc.d.ts); give it to your editor or agent.
The oc API
| Call | Permission | Does |
|---|---|---|
oc.ready | none | promise with {pluginId, sourceId, settings, permissions, preview} |
oc.param(key, default) | none | a setting from the query, cast to the type of default |
oc.chat.subscribe({channel?}) | chat.read | start reading the chat; events through oc.chat.on("message" | "delete" | "clear" | "status", fn) |
oc.chat.say(text, {channel?, as?, replyTo?}) | chat.send | write as the bot (as: "bot", default) or the streamer |
oc.storage.get/set/delete/list(prefix) | storage | JSON values of the plugin on this computer |
oc.storage.update(key, fn) | storage | safe read-modify-write |
oc.storage.onChange(fn) | storage | another copy of the widget changed the data |
oc.net.localGet(target, path) | net.local | GET to a program on this computer (needs a netLocal rule in the manifest) |
oc.lifecycle.onStop(fn) | none | up to 3 s to save data when the app quits |
Notes: the storage key is up to 128 characters of A–Z a–z 0–9 _ . : / -, a value is any JSON up to 256 KB, the quota is 5000 keys and 8 MB. In the editor preview say is disabled (replies would be duplicated). Sending is limited to about 18 messages per 30 s per bot.
oc.chat.on("message", async (m) => {
if (m.text.startsWith("!task ")) {
await oc.storage.update("tasks", (list = []) => [...list, m.text.slice(6)]);
}
});
oc.storage.onChange((c) => { if (c.key === "tasks") render(c.value || []); });
Sandbox
A widget runs in an iframe with sandbox="allow-scripts allow-forms allow-popups allow-modals" and without allow-same-origin. It has an opaque origin: no localStorage, no cookies, no access to the app API. fetch and WebSocket to external addresses work (the other side must allow CORS). The plugin’s own files (/plugins/<id>/…) are served with CORS *.
Publish
Put the plugin into a GitHub repository as plugins/<id>/ (with plugin.json and the entry file) and share the repository address: users add it in Add Source → Plugin store…. See compico/oc-plugins for examples (osu-np, fps-meter). A changelog.json next to plugin.json is shown to users after an update: [{ "version": "1.2.0", "date": "2026-10-27", "changes": ["what is new"], "migration": "what to do after updating" }].
Part 2. Standalone plugin in Go
A standalone plugin is passive: it declares routes and handlers, and the host calls them. It does not listen to anything by itself and does not run in the background. The host owns long-lived resources (timers, network requests, the Twitch connection).
Set up
Go 1.24 or newer is needed (//go:wasmexport). The SDK has no dependencies.
mkdir hello && cd hello
go mod init example.com/hello
go get github.com/compico/overlaycomposer/pkg/ocplugin
main.go:
package main
import "github.com/compico/overlaycomposer/pkg/ocplugin"
func init() {
p := ocplugin.New(ocplugin.Meta{
ID: "hello", // a-z 0-9 -, up to 64 characters; also the URL segment
Name: "Hello",
Version: "0.1.0", // semver
Permissions: []string{ocplugin.PermStorage},
})
p.GET("/greet", func(c *ocplugin.Ctx) error {
n, _, _ := ocplugin.Load[int]("count")
_ = ocplugin.Store("count", n+1)
return c.JSON(200, map[string]any{"hello": c.Query("name"), "count": n + 1})
})
}
func main() {} // required to build a reactor; stays empty
Build:
GOOS=wasip1 GOARCH=wasm go build -buildmode=c-shared -o hello.wasm .
Install: copy hello.wasm into the plugins folder (🧩 Plugins → Open folder), press Rescan, then grant the permissions the plugin asks for (🧩 Plugins, the plugin card). Test: http://127.0.0.1:8000/plugins/hello/api/greet?name=oc returns {"count":1,"hello":"oc"}.
Rules that make it work:
Newis called once, frominit(); one.wasmholds one plugin. Route paths start with/.- The plugin id must not equal the id of an HTML plugin.
- A Go plugin weighs about 3 MB (the Go runtime); that is normal.
Behaviour you must design for
- Calls come one at a time, a call is limited to 10 s. A panic, trap or timeout recreates the instance; 5 failures within a minute put the plugin into
faileduntil a manual restart. - Keep state in the host storage (
Store/Load), not in variables: the instance is recreated after a failure, after permissions change and after settings change. OnInitruns many times. Before the user grants a permission, host operations returnpermission denied. InOnInitthat is normal: do not return an error (an error fromOnInitputs the plugin intofailed).- A route handler answers immediately. Long work goes through host operations that return later as events (
Fetch→OnHTTPResponse,SetTimer→OnTimer). - There are no threads in
wasip1: goroutines run only inside a host call. time.Now()andcrypto/randwork normally (time is UTC).- Logging:
ocplugin.Info/Warn/Error/Debug(msg, "key", value, …), plus stdout/stderr, goes to the app log asplugin=<id>.
Routes and requests
p.POST("/add", func(c *ocplugin.Ctx) error {
var in struct{ Text string `json:"text"` }
if err := c.Bind(&in); err != nil {
return c.Error(400, "bad json")
}
if in.Text == "" {
return c.Error(422, "text is empty")
}
return c.JSON(201, map[string]any{"ok": true})
})
p.GET/POST/PUT/PATCH/DELETE(path, handler) become /plugins/<id>/api<path>. Ctx has Query(key), Bind(&v), JSON(status, v), NoContent(), Error(status, msg), plus Method and Path. A returned error becomes a bare 500 (details only go to the log). A panic in a handler becomes a 500 and the plugin keeps running. The response is always application/json.
Safety of routes: a request from another origin (including a widget iframe) is rejected by the app, other devices need a pairing token, so GET handlers must be free of side effects (any page can trigger them). Treat all input as untrusted.
Host operations (permissions)
Declare permissions in Meta.Permissions; the user grants them.
| Permission | SDK | Does |
|---|---|---|
storage (PermStorage) | Load[T](key), Store(key, v), Remove(key) | JSON values in the app database (private to the plugin) |
timer (PermTimer) | SetTimer(id, d, repeat), ClearTimer(id), p.OnTimer(id, f) | 50 ms to 24 h, up to 16 timers, the same id replaces |
net.http (PermNetHTTP) | Fetch(id, FetchRequest{Method, URL, Body}), p.OnHTTPResponse(id, f) | http(s) only; request body up to 256 KB, response up to 1 MB, 15 s, 8 at a time, up to 3 redirects; loopback, private, link-local and CGNAT addresses are blocked |
twitch.redemption (PermRedeem) | p.OnRedemption(f), FulfillRedemption(rewardID, id), CancelRedemption(rewardID, id) | channel point rewards; cancelling refunds the points |
events.publish (PermPublish) | Publish(topic, v), PublishRetained(topic, v) | events for widgets, add-ons and the Deck |
chat.send (PermChat) | Say(text) | a message in the streamer’s channel as the bot: up to 300 characters, burst 3 then 1 per 3 s; the host chooses channel and account |
A failed operation returns an error (for example permission denied).
Timer
p.OnInit(func() error {
_ = ocplugin.SetTimer("tick", 30*time.Second, true) // denied before the grant: that is fine
return nil
})
p.OnTimer("tick", func() { ocplugin.Info("tick") })
HTTP request
_ = ocplugin.Fetch("rates", ocplugin.FetchRequest{URL: "https://example.com/api/rates"})
p.OnHTTPResponse("rates", func(r ocplugin.HTTPResponse) {
if r.Error != "" || r.Status != 200 {
return
}
_ = ocplugin.Store("rates", r.Body) // r.Body is a string
})
Twitch reward
p := ocplugin.New(ocplugin.Meta{
ID: "orders", Name: "Orders", Version: "0.1.0",
Permissions: []string{ocplugin.PermStorage, ocplugin.PermRedeem, ocplugin.PermChat},
ConfigSchema: map[string]any{
"rewardId": map[string]any{"type": "string", "format": "twitch.reward", "title": "Reward"},
},
})
p.OnRedemption(func(r ocplugin.Redemption) {
// r.Input is text typed by the viewer: untrusted
var cfg struct{ RewardID string `json:"rewardId"` }
_ = p.Config(&cfg)
if r.RewardID != cfg.RewardID {
return
}
// ... validate r.Input, save the order with Store ...
_ = ocplugin.FulfillRedemption(r.RewardID, r.ID) // or CancelRedemption: the points are returned
_ = ocplugin.Say("@" + r.UserName + " accepted")
})
Redemption has ID, RewardID, RewardTitle, UserID, UserLogin, UserName, Input, Status, RedeemedAt. The reward must be created by the app (in the plugin settings: New reward…), otherwise Twitch refuses to change its status. The app subscribes to Twitch EventSub automatically while an enabled plugin has the twitch.redemption permission; repeated deliveries of the same redemption are dropped by id.
Settings (configSchema)
Meta.ConfigSchema describes the form shown by the app: fields of type string, integer/number, boolean, with title and description. "format": "twitch.reward" makes a reward picker. Read the values with p.Config(&struct{...}) (available from OnInit); saving the settings restarts the plugin.
Publishing events
Declare topics in Meta.Events and add the events.publish permission:
Events: []ocplugin.EventDecl{{ID: "now", Name: "Now playing"}, {ID: "commands"}},
ocplugin.Publish("commands", v) publishes an event; PublishRetained("now", v) also keeps the last value so a new subscriber gets it at once (use for state, not for commands). A topic is a-z0-9._-, up to 64 characters, up to 32 per plugin; data is JSON up to 64 KB; about 20 events/s on average per plugin.
Subscribers:
- a widget or settings page of the same plugin:
oc.plugin.subscribe("now", (data, meta) => …), wheremetais{topic, seq, retained}; - an external program: WebSocket
ws://127.0.0.1:8000/plugins/<id>/ws. Frames are JSON text: send{"t":"sub","topic":"now"}, receive{"t":"event","topic":"now","data":…,"seq":7,"retained":true}; send{"t":"ping"}now and then and reconnect on loss (the retained value comes again aftersub). Allowed origins: none, the same host,music-application://desktop.
UI inside the .wasm: widgets and a settings page
Put HTML, JS, CSS, images and fonts into a folder (for example ui/), declare them in Meta, and pack the folder into the same .wasm with ocpack:
Widgets: []ocplugin.Widget{{ID: "queue", Name: "Queue", Entry: "queue.html", Width: 360, Height: 240}},
Settings: "settings.html", // a page shown under 🧩 Plugins → Settings
# in a clone of github.com/compico/overlaycomposer
go run ./cmd/ocpack pack hello.wasm ./ui # appends the oc.assets section; running again replaces it
go run ./cmd/ocpack list hello.wasm
In GitHub Actions use uses: compico/overlaycomposer/actions/ocpack@<tag-or-commit> with wasm: and ui: inputs. Rules: relative paths with / and the characters A–Z a–z 0–9 . _ ~ @ -, no .., no hidden files; extensions only html htm js mjs css json txt png jpg jpeg gif webp svg ico woff woff2 mp3 ogg wav; up to 256 files, 2 MB per file, 8 MB in total. If the file named by Entry or Settings is missing the plugin does not load.
Pages are served at /plugins/<id>/ui/<path> (relative links like app.js work). Widgets appear in Add Source → Widgets marked standalone. In the page include the SDK and call your own plugin:
<script src="/plugin-sdk/oc.js"></script>
<script>
oc.plugin.get("/queue").then(({ body }) => render(body)); // GET /plugins/<id>/api/queue
oc.plugin.post("/started", { id: "abc" });
oc.plugin.subscribe("now", (data) => show(data));
</script>
oc.plugin.call/get/post go through the overlay page, not through fetch from the sandbox; they reach only routes declared by this plugin (up to 8 concurrent calls, 15 s). The editor preview calls the plugin too (oc.ready gives info.preview === true): do not send state-changing actions from a preview. The settings page also has oc.storage.* (with the storage permission) and the same oc.plugin.*.
Every plugin page is served with Content-Security-Policy: sandbox allow-scripts; it cannot reach the app API.
Tests
The SDK layer builds only for wasip1, but handlers are plain functions. Replace the host in an ordinary go test:
func TestGreet(t *testing.T) {
store := map[string]json.RawMessage{}
ocplugin.SetHost(func(op string, arg []byte) []byte {
switch op {
case "storage.get":
var a struct{ Key string }
_ = json.Unmarshal(arg, &a)
if v, ok := store[a.Key]; ok {
return []byte(`{"found":true,"value":` + string(v) + `}`)
}
return []byte(`{"found":false}`)
case "storage.set":
var a struct {
Key string
Value json.RawMessage
}
_ = json.Unmarshal(arg, &a)
store[a.Key] = a.Value
}
return []byte(`{}`)
})
// call your logic (kept in separate functions) and assert
}
Keep the logic (queues, parsing) in functions that do not touch the SDK and test those directly; wasm/music in oc-plugins is a full example.
Publish a standalone plugin
In compico/oc-plugins (or your own repository built the same way): the plugin lives in wasm/<id>/ with its own go.mod (the folder name equals the id), optional ui/ and a README.md.
node scripts/wasm.mjs build <id>runsgo vet,go test, buildsdist/<id>.wasm(packingui/withocpack) and prints the metadata read from the file.npm testvalidates every manifest.- Raise
Versionfor every code change. After merge tomainCI creates a release<id>-v<version>with<id>.wasmand a sha256; a PR that changes code without raising the version fails the check. - Users install the file from the release (see Widgets and plugins).
Part 3. Other languages (ABI)
A .wasm file for the wasip1 target (a reactor) with these exports and one import works in any language. Everything except signatures is JSON, so new features do not break existing plugins. i64 is (ptr << 32) | len of a buffer in the plugin memory, 0 means empty.
| Export | Purpose |
|---|---|
alloc(n: i32) -> i32 | allocate at least n bytes |
dealloc(ptr: i32) | free a buffer |
oc_meta() -> i64 | pure function: metadata JSON (called on a throwaway instance, host_call is not available) |
oc_init(ptr, len) -> i64 | {"apiVersion":1,"config":{…}}; the result is ignored |
oc_call(name_ptr, name_len, arg_ptr, arg_len) -> i64 | a route handler (by the name from oc_meta) or on_event |
Import (module oc): host_call(op_ptr, op_len, arg_ptr, arg_len) -> i64 runs a host operation: JSON argument in, JSON result out ({"error":"…"} on failure). If _initialize is exported the host calls it. Go: -buildmode=c-shared with //go:wasmexport and //go:wasmimport; Rust: cdylib for wasm32-wasip1.
oc_meta result:
{
"id": "music", "name": "Music requests", "version": "0.1.0", "apiVersion": 1,
"permissions": ["storage", "timer", "net.http", "twitch.redemption", "events.publish", "chat.send"],
"subscriptions": ["twitch.redemption"],
"routes": [{"method": "GET", "path": "/next", "handler": "next"}],
"events": [{"id": "now", "name": "Now playing"}],
"widgets": [{"id": "queue", "name": "Queue", "entry": "queue.html", "width": 360, "height": 240}],
"settings": "settings.html",
"configSchema": {"rewardId": {"type": "string", "format": "twitch.reward", "title": "Reward"}}
}
A route handler gets {"method","path","query":{…},"body":<json|null>} and returns {"status":200,"body":<json>}. Events go to the handler named on_event with {"type","data"}: twitch.redemption, timer ({"id"}), http.response ({"id","status","body","error"}).
Host operations (host_call): log, storage.get/set/delete, timer.set/clear, http.fetch, twitch.redemption.update, events.publish, chat.send. Arguments are the JSON objects shown by the Go SDK functions above (for example storage.set takes {"key","value"}, timer.set takes {"id","ms","repeat"}, chat.send takes {"text"}).
A Rust SDK (like ocplugin for Go) is planned; see the issue #136. Rust plugins on the same ABI weigh about 100 KB.
Checklist for an agent
- Choose the kind (Part 1 or Part 2). If the plugin needs Twitch rewards, timers, bot messages or must survive without an open widget, it is standalone.
- Write
Meta/plugin.jsonwith the minimum permissions. - Keep state in storage; never rely on variables or background work; answer routes immediately.
- Treat every viewer text (
Redemption.Input, chat messages) as untrusted; never build HTML from it withinnerHTML. - Raise the version on every change.
- Build (
GOOS=wasip1 GOARCH=wasm go build -buildmode=c-shared -o <id>.wasm .), install, grant permissions in 🧩 Plugins, check the log (plugin=<id>).