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 pluginStandalone plugin (WebAssembly)
What it isa folder with plugin.json and a web pageone .wasm file, runs inside the app
LanguageHTML, JS, CSS (any web stack)Go (SDK provided); Rust and others through the ABI
Runsin a sandboxed iframe of the overlayon the server, no window
Good forwhat is drawn on the stream: chat, counters, alertslogic that must keep running: Twitch rewards, queues, timers, HTTP calls, bot messages, events
Can have a UIit is the UIyes: 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>/ (default index.html).
  • Setting types: string, text, number, range, bool, color (#rrggbb), font, select (needs options). min, max, step for number and range; group titles a section; help is 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 are 32, booleans true or false.

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

CallPermissionDoes
oc.readynonepromise with {pluginId, sourceId, settings, permissions, preview}
oc.param(key, default)nonea setting from the query, cast to the type of default
oc.chat.subscribe({channel?})chat.readstart reading the chat; events through oc.chat.on("message" | "delete" | "clear" | "status", fn)
oc.chat.say(text, {channel?, as?, replyTo?})chat.sendwrite as the bot (as: "bot", default) or the streamer
oc.storage.get/set/delete/list(prefix)storageJSON values of the plugin on this computer
oc.storage.update(key, fn)storagesafe read-modify-write
oc.storage.onChange(fn)storageanother copy of the widget changed the data
oc.net.localGet(target, path)net.localGET to a program on this computer (needs a netLocal rule in the manifest)
oc.lifecycle.onStop(fn)noneup 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:

  • New is called once, from init(); one .wasm holds 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 failed until 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.
  • OnInit runs many times. Before the user grants a permission, host operations return permission denied. In OnInit that is normal: do not return an error (an error from OnInit puts the plugin into failed).
  • 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() and crypto/rand work normally (time is UTC).
  • Logging: ocplugin.Info/Warn/Error/Debug(msg, "key", value, …), plus stdout/stderr, goes to the app log as plugin=<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.

PermissionSDKDoes
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) => …), where meta is {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 after sub). 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> runs go vet, go test, builds dist/<id>.wasm (packing ui/ with ocpack) and prints the metadata read from the file. npm test validates every manifest.
  • Raise Version for every code change. After merge to main CI creates a release <id>-v<version> with <id>.wasm and 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.

ExportPurpose
alloc(n: i32) -> i32allocate at least n bytes
dealloc(ptr: i32)free a buffer
oc_meta() -> i64pure 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) -> i64a 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

  1. 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.
  2. Write Meta/plugin.json with the minimum permissions.
  3. Keep state in storage; never rely on variables or background work; answer routes immediately.
  4. Treat every viewer text (Redemption.Input, chat messages) as untrusted; never build HTML from it with innerHTML.
  5. Raise the version on every change.
  6. Build (GOOS=wasip1 GOARCH=wasm go build -buildmode=c-shared -o <id>.wasm .), install, grant permissions in 🧩 Plugins, check the log (plugin=<id>).