SheevChat Overlay Widget Developer Wiki

Build visual packages for Overlay Builder without modifying SheevChat's native widgets. This reference explains which package type to use, what is supported today, how third-party code stays isolated, and how widgets, themes, action packs, and community bundles fit together.

SheevChat marketplace packages are small add-ons that teach SheevChat how to do more. Some connect SheevChat to another app, some add overlay widgets, some style widgets that already exist, and some bundle a complete setup. You do not edit SheevChat itself: describe the package in a manifest, include its files, and SheevChat decides where it can safely run.

Start Here: What Are You Making?

Streamer Or Theme Seller

If you have art, CSS, or a StreamElements widget, first decide whether you are changing an existing widget or adding new behavior. Use a theme for documented appearance settings. Use a widget pack when the package contains custom HTML or JavaScript. A StreamElements export should retain html.txt, css.txt, js.txt, fields.txt, and data.txt. Include useful previews, and never include secrets or customer data.

App Developer

Document how your app accepts commands and whether it emits events. Build an action library for its connection, actions, dynamic lists, authentication, and supported event subscriptions. Keep it declarative. If it also needs overlay output, publish that as a separate widget pack; a community pack can connect the pieces.

AI-Assisted Creator

Give the AI this wiki and the target app's authoritative API documentation. Require it to use only features marked available, report unsupported gaps instead of inventing fields, generate the appropriate manifest, and list what must be tested in SheevChat. A complete copyable prompt appears near the end of this page.

Choose The Correct Package

Do not use the deprecated overlay_pack type. Creators assemble layouts in Overlay Builder. Package behavior as a widget, appearance as a theme, and setup recipes as a community pack.

Hard Boundaries

• Themes change appearance, not behavior.
• Widgets add visual or runtime behavior.
• Action packs connect to apps and expose actions, sources, and events.
• Chat games declaratively register managed commands and compose only the resources, state, sessions, prompts, votes, and overlay events allowed by their runtime.
• Community packs connect existing packages and recipes without hiding what will be installed.
• Third-party widget code stays isolated from SheevChat's native widgets and main Overlay Builder document.
• A widget pack must not add fields to, remove fields from, or change defaults for built-in widgets.
• Normal Marketplace installs should not require end users to edit JSON manually.
• Unknown provider values render as safe placeholders. They are never assumed to be StreamElements widgets.

Current Support Levels

Use StreamElements compatibility for an actual StreamElements export. Use sheevchat-widget-v1 for new third-party widget behavior. If you only need to restyle a built-in SheevChat widget, use a theme pack and its sheevchat-theme-v1 presentation runtime.

Minimal Package Examples

Start with the smallest honest package, validate it, and expand only when the runtime needs more.

Minimal Built-In Theme

{
  "schemaVersion": 1,
  "id": "simple-chat-theme",
  "type": "theme_pack",
  "name": "Simple Chat Theme",
  "publisher": "Example Creator",
  "version": "1.0.0",
  "requires": [{ "type": "builtin_widget", "id": "chat", "required": true }],
  "themes": [{
    "id": "clean",
    "label": "Clean",
    "target": "chat_overlay",
    "settings": { "textColor": "#ffffff", "accentColor": "#8a6cff" }
  }]
}

Minimal Developer Widget Shape

This is the active v1 developer-widget shape:

{
  "schemaVersion": 1,
  "id": "simple-clock-widget",
  "type": "widget_pack",
  "name": "Simple Clock Widget",
  "publisher": "Example Creator",
  "version": "1.0.0",
  "compatibility": {
    "provider": "sheevchat-widget",
    "kind": "clock",
    "api": "sheevchat-widget-v1"
  },
  "capabilities": ["run_overlay_iframe"],
  "eventSubscriptions": ["chat.message", "widget.action"],
  "widget": {
    "files": {
      "html": "widget/index.html",
      "css": "widget/style.css",
      "js": "widget/widget.js"
    }
  },
  "fields": [{ "id": "textColor", "type": "colorpicker", "label": "Text color" }],
  "fieldData": { "textColor": "#ffffff" }
}

The HTML file is required. JavaScript and subscriptions are optional for static widgets; declare settings.staticWidget: true when the widget intentionally consumes no events.

Minimal Community Bundle

{
  "schemaVersion": 1,
  "id": "simple-stream-setup",
  "type": "community_pack",
  "name": "Simple Stream Setup",
  "publisher": "Example Creator",
  "version": "1.0.0",
  "requires": [
    { "type": "widget_pack", "id": "simple-clock-widget", "required": true },
    { "type": "theme_pack", "id": "simple-clock-themes", "required": false }
  ],
  "recipes": [{
    "type": "automation",
    "name": "Show clock on stream start",
    "enabledByDefault": false
  }]
}

Minimal Chat Game Shape

Chat games are JSON-only command packages. They cannot include JavaScript, SQL, shell commands, unrestricted expressions, filesystem access, or arbitrary request URLs. The active runtime is sheevchat-chat-game-v2:

{
  "schemaVersion": 2,
  "id": "simple-die",
  "type": "chat_game",
  "name": "Simple Die",
  "publisher": "Example Creator",
  "version": "1.0.0",
  "runtime": "sheevchat-chat-game-v2",
  "capabilities": ["managed_commands", "weighted_random"],
  "resources": [],
  "state": [],
  "tables": {
    "die": [
      { "id": "one", "label": "1", "weight": 1, "value": 1 },
      { "id": "six", "label": "6", "weight": 1, "value": 6 }
    ]
  },
  "commands": [{
    "id": "roll",
    "trigger": "!rolldie",
    "aliases": ["!dice"],
    "arguments": [],
    "steps": [{ "op": "choose", "table": "die", "result": "roll" }],
    "response": "@{identity.username} rolled {result.roll.value}."
  }]
}

The runtime also supports package resources and inventory, cached host-approved prompt sources, scoped state, sessions and multiplayer, community contributions, voting, leaderboards, command fallbacks, streamer-managed aliases, transactions, and optional companion-overlay events. See the Chat Game Creator Wiki for the complete active boundary.

Widget Pack Manifest

Non-action packages use a root-level manifest.json inside a .sheevpack or .zip package.

{
  "schemaVersion": 1,
  "id": "minimalist-glow-chat",
  "type": "widget_pack",
  "name": "Minimalist Glow Chat",
  "publisher": "Example Creator",
  "version": "1.0.0",
  "description": "An isolated custom chat widget for Overlay Builder.",
  "targets": ["overlay", "chat"],
  "tags": ["chat", "minimal", "glow"],
  "compatibilityTags": ["chat-widget", "streamelements-custom-widget"],
  "capabilities": ["run_overlay_iframe", "receive_sheevchat_events"],
  "requires": [],
  "compatibility": {
    "provider": "streamelements",
    "kind": "custom_widget",
    "api": "custom_widgets",
    "listeners": ["message", "follower-latest", "subscriber-latest"]
  }
}

Identity Rules

• id uses lowercase letters, numbers, _, or -, is 3–80 characters, and starts and ends with a letter or number.
• version uses semver-style text such as 1.0.0 or 1.1.0-beta.2.
• type is widget_pack for new widget behavior.
• targets are short discovery labels such as overlay, chat, spotify, game, or vtuber.
• compatibilityTags are stable machine-friendly matching labels.
• Keep the provider explicit.

Provider Lanes

StreamElements Compatibility

Use only for a StreamElements custom widget export:

{
  "compatibility": {
    "provider": "streamelements",
    "kind": "custom_widget",
    "api": "custom_widgets"
  }
}

SheevChat loads the original HTML, CSS, and JavaScript in a sandboxed iframe owned by the isolated Marketplace Item widget. It does not merge imported fields or behavior into Chat, Spotify, Giveaway, Credits, YouTube Media, Clip, Image, Text, or Alert Box.

First-Party SheevChat Widgets

provider: "sheevchat" is reserved for SheevChat-owned or tightly controlled native renderers. A native manifest can describe widgets and editable fields, but declaring this provider does not make arbitrary third-party code execute natively.

The desktop may own the renderer contract, but the widget manifest, defaults, previews, and themes still belong in an installed Marketplace package; first-party proof packages are not assumed to be bundled into the desktop app.

{
  "compatibility": {
    "provider": "sheevchat",
    "kind": "clock",
    "api": "native-clock-v1"
  },
  "widgets": [
    {
      "id": "clock",
      "label": "Clock",
      "kind": "clock",
      "entry": "widgets/clock.json"
    }
  ]
}

Developer Widget Runtime

The active developer lane uses provider: "sheevchat-widget" with api: "sheevchat-widget-v1". It runs package HTML, CSS, and JavaScript inside an isolated Marketplace Item iframe. SheevChat owns the websocket, event routing, state endpoint, asset/font requests, and audio requests; the iframe owns only its DOM and widget logic.

{
  "compatibility": {
    "provider": "sheevchat-widget",
    "kind": "spin-wheel",
    "api": "sheevchat-widget-v1"
  },
  "capabilities": [
    "run_overlay_iframe",
    "receive_sheevchat_events",
    "invoke_sheevchat_actions",
    "store_local_widget_state"
  ],
  "eventSubscriptions": ["chat.message", "event.follow", "widget.action"],
  "widget": {
    "files": {
      "html": "widget/index.html",
      "css": "widget/style.css",
      "js": "widget/widget.js"
    }
  }
}

The HTML entry is required and all runtime file references must exist inside the package. Missing JavaScript or subscriptions produce developer warnings rather than install errors because static widgets are valid. An unsupported API or an escaping/missing HTML path blocks installation.

The iframe exposes:

SheevWidget.apiVersion
SheevWidget.packageId
SheevWidget.title
SheevWidget.settings
SheevWidget.fieldData
SheevWidget.runtime()
SheevWidget.visible()
SheevWidget.on(type, handler)
SheevWidget.off(type, handler)
SheevWidget.ready()
SheevWidget.log(message)
SheevWidget.error(error)
SheevWidget.requestAsset(url)
SheevWidget.requestFont(href)
SheevWidget.playAudio(src, options)
SheevWidget.resize(width, height)
SheevWidget.setVisible(visible)
SheevWidget.getState()
SheevWidget.setState(state)

HTML/CSS support {{fieldName}} and safe {fieldName} substitution. Relative HTML and CSS assets are rewritten to guarded package-local routes; requestAsset("assets/logo.png") resolves dynamic assets. setVisible(false) hides the iframe surface without destroying it or clearing its state.

Common neutral subscriptions include chat.message, event.follow, event.sub, event.raid, event.cheer, event.superchat, event.twitch_ad_schedule, widget-button, and widget.action. chat, event, and * are broad aliases; avoid the noisy wildcard in production.

SheevWidget.on('init', () => SheevWidget.ready());

SheevWidget.on('chat.message', ({ event, replay }) => {
  renderMessage(event.user, event.message, event.platform);
});

SheevWidget.on('widget.action', ({ event }) => {
  runAction(event.field, event.data?.payload);
});

Interactive widgets may declare button fields. Overlay Builder clicks and the built-in Trigger Marketplace Widget action both deliver the field/action key through event.field; optional action JSON arrives at event.data.payload. The runtime also emits snapshot, visibilityChanged, settingsChanged, assetReady, fontReady, audioPlayback, and shutdown.

StreamElements Export Layout

SheevChat recognizes the classic custom-widget export:

widget.ini
html.txt
css.txt
js.txt
fields.txt
data.txt

Required files:

• html.txt
• css.txt
• js.txt
• fields.txt
• data.txt

widget.ini is optional for detection but should be included when available. Relative HTML and CSS assets are rewritten to safe package-local routes at runtime.

Editable Fields

For StreamElements-compatible widgets:

• data.txt supplies default fieldData.
• fields.txt defines the controls shown in the Marketplace Item inspector.
• Each placed widget stores its own fieldDataOverrides.
• Runtime data is merged as defaults plus the placed widget's overrides before onWidgetLoad.
• {{fieldName}} and safe {fieldName} template values are substituted from the merged fields.
• Hidden fields remain hidden.
• Field descriptions and help text should explain creator-facing effects.

Supported controls include toggles, dropdowns/selects, color pickers, text and multiline text, numbers/sliders, Google fonts, image/video/audio/media paths, hidden values, buttons, and grouped controls. button sends a widget action instead of storing a setting.

social_accounts stores repeatable { platform, username, url?, icon?, label?, logoStyle? } objects for social tickers and similar widgets. Packages may supply platformOptions and enable custom links with showLinkField: true or allowCustomLinks: true. Runtime code should ignore incomplete draft rows.

Runtime Isolation

StreamElements-compatible code runs inside a sandboxed iframe:

• The widget cannot access the parent Overlay Builder DOM.
• Built-in widgets never load the StreamElements runtime.
• The parent owns the SheevChat websocket and distributes bounded event data to widget frames.
• Widget frames should not open duplicate SheevChat websocket connections.
• Relative package assets resolve through safe local marketplace routes.
• Script errors and rejected promises are forwarded to the overlay console with package context.
• Iframes persist during normal updates so animations do not restart for every message.

Use window.sheevchatResolveAsset(path) when compatible widget JavaScript must resolve a packaged asset dynamically.

Events And Sample Data

The compatibility host supports onWidgetLoad, onEventReceived, and onSessionUpdate. Live chat is delivered with listener: "message". Common mapped event listener names include:

• follower-latest
• subscriber-latest
• raid-latest
• cheer-latest
• superchat-latest
• sponsor-latest
• tip-latest
• host-latest
• redemption-latest
• purchase-latest
• merch-latest
• charity-latest

Only declare listeners the widget actually consumes. Fields such as platform, provider, user id, display name, message, amount, count, currency, viewers, badges, and emotes are supplied when SheevChat has an equivalent value. Do not assume every platform supplies every field.

Overlay Builder provides sample chat and alert events for local testing. A widget should handle missing optional values and representative sample data without crashing.

Local Widget State

StreamElements-compatible widgets can use bounded SE_API.store and SE_API.counters shims.

• State is scoped to the installed package id, not each canvas instance.
• Store values must be JSON-safe.
• Functions, DOM nodes, symbols, cyclic objects, and class instances are not persisted.
• Keys, strings, nesting depth, and total state size are capped.
• Persistence failures fall back to memory for the current page load and are logged.
• Store and counter changes emit compatibility update events.

Do not use widget state as a secret store. Do not place credentials or platform tokens in fields, assets, or persisted widget state.

Assets And Previews

Bundle runtime assets whenever possible. Package file references must be relative and remain inside the package. Do not use .., absolute paths, or drive letters.

{
  "previews": [
    { "file": "previews/card.png", "label": "Marketplace card", "type": "image" },
    { "file": "previews/demo.mp4", "label": "OBS preview", "type": "video" }
  ]
}

Catalog preview URLs must use HTTPS. Bundled previews are useful after download; catalog-hosted previews are preferred for marketplace browsing.

Marketplace and Installed Apps cards now display catalog previewUrls and explicitly listed bundled previews[]. Installed preview files are served only when the manifest lists them. Package details also show trust, capabilities, provider/kind/API, dependencies, tags, compatibility tags, release notes, package id/version, minimum SheevChat version, and install/update state. Missing required dependencies can link to their Marketplace install action when available.

Useful catalog/manifest metadata:

{
  "publisherId": "example-creator",
  "trust": "verified_creator",
  "capabilities": ["run_overlay_iframe", "receive_sheevchat_events"],
  "previewUrls": ["https://marketplace.sheevchat.com/previews/example.png"],
  "changelog": "Initial Marketplace release."
}

Theme Packs

A theme changes presentation, not application behavior. It may apply documented theme-safe settings or provide isolated presentation HTML/CSS/JavaScript through sheevchat-theme-v1. SheevChat still owns connections, filtering, emotes, queues, actions, and source state. Themes must not add app connections, moderation, command parsing, queue rules, or hidden automations.

Theme A Built-In Widget

{
  "id": "neon-glow-chat",
  "type": "theme_pack",
  "name": "Neon Glow Chat",
  "version": "1.0.0",
  "requires": [
    { "type": "builtin_widget", "id": "chat", "required": true }
  ],
  "themes": [{
    "id": "neon",
    "label": "Neon",
    "target": "chat_overlay",
    "renderer": {
      "api": "sheevchat-theme-v1",
      "html": "themes/neon/index.html",
      "css": "themes/neon/style.css",
      "js": "themes/neon/theme.js"
    },
    "settings": { "textColor": "#ffffff", "accentColor": "#8a6cff" },
    "frame": { "width": 760, "height": 600 }
  }]
}

Stable dependency ids include chat, spotify, giveaway, credits, youtube_media, clip, image, text, and alert_box. Renderer targets are chat_overlay, spotify_overlay, giveaway_overlay, credits_overlay, youtube_media_overlay, clip_overlay, image, text, and alert_box.

At least one renderer file should exist; HTML is recommended. Renderer files and their asset references must remain package-local. The iframe receives settings, frame, and target-specific data through postMessage.

SheevTheme.on('init', ({ settings, data, frame }) => {
  render(settings, data, frame);
  SheevTheme.ready();
});

SheevTheme.on('update', ({ settings, data, frame }) => {
  render(settings, data, frame);
});

The active API provides on, ready, log, error, requestAsset, requestFont, playAudio, setVisible, and getState, plus package, theme, target, and API identifiers. Runtime messages include init, update, visibilityChanged, assetReady, fontReady, audioPlayback, and shutdown.

Built-In Theme Data Contracts

Spotify themes should use hasTrack, hasArt, and hasDuration guards; use progress.percent for 0–100 bars and progress.ratio for 0–1 math. For ticking time, advance the numeric progress from progress.sampledAt while playing and clamp it to the duration. Do not open Spotify connections. Use the supplied palette when artwork color extraction fails, and keep the renderer responsive inside the manifest's natural frame.

Chat themes should use messages for chat, events for activity, feed for a combined timestamp-sorted display, and viewers or viewerGroups for presence. Rows include normalized platform, user, message/event, badges, roles, and timestamps. SheevChat applies platform and hidden-account filters before sending visible data; themes must not recreate moderation logic or open chat sockets.

Theme A Widget Pack

{
  "id": "stream-avatars-pixel-theme",
  "type": "theme_pack",
  "name": "Pixel Avatar Theme",
  "version": "1.0.0",
  "requires": [
    {
      "type": "widget_pack",
      "id": "stream-avatars-overlay",
      "version": ">=1.0.0",
      "required": true
    }
  ]
}

Third-party widget themes may change only the fields that widget declares themeable.

Dependencies

Dependencies are install-graph metadata. They do not execute code.

{
  "type": "action_library",
  "id": "stream-avatars-control",
  "version": ">=1.0.0",
  "required": false,
  "reason": "Enables avatar controls from SheevPad and automations."
}

Supported dependency types are action_library, widget_pack, theme_pack, community_pack, chat_game, and builtin_widget.

• required: true means the package is not fully usable without the dependency.
• required: false or optional: true describes a soft dependency.
• Themes depend on the widget they style instead of bundling duplicate behavior.
• Use semver/range text even while version enforcement remains informational in some surfaces.

Capabilities And Trust

Declare only capabilities the package uses. Relevant widget capabilities include:

• run_overlay_iframe
• store_local_widget_state
• receive_sheevchat_events
• invoke_sheevchat_actions
• install_dependencies
• add_disabled_recipes

Action-pack dependencies may separately request local WebSocket, HTTP, TCP, UDP, MQTT, IPC, OAuth, or endpoint-file access. A visual theme should normally request no runtime or network capability.

Public trust labels:

• Official SheevChat
• Verified Partner
• Verified Creator
• Marketplace Verified
• Community
• Local Import
• Unverified

A community bundle inherits the lowest trust level among its dependencies.

Widget Plus Action Pack Pattern

Keep app control and overlay rendering separate:

1. An action_library connects to the target app and exposes actions or events.
2. A widget_pack renders the overlay and optionally depends on the action pack.
3. A theme_pack changes declared visual fields.
4. A community_pack installs the pieces and offers disabled-by-default recipes.

This structure lets users replace the theme without replacing behavior, use the control pack without the overlay, and understand every installed permission.

Developer Testing Checklist

• The package id and version follow the identity rules.
• manifest.json is at the package root.
• The package type matches the behavior being added.
• compatibility.provider names a supported lane.
• Every capability is necessary and visible to the user.
• Every required dependency exists and has a clear reason.
• All file references are package-relative and traversal-safe.
• The widget renders with sample data before OBS testing.
• A sheevchat-widget-v1 package has an existing, package-local HTML entry and declares only the events it consumes.
• An intentionally event-free developer widget declares settings.staticWidget: true or compatibility.static: true.
• Widget actions handle both editor button clicks and the Trigger Marketplace Widget action without trusting payload JSON.
• A sheevchat-theme-v1 renderer uses a documented target/data contract and never opens its own SheevChat or platform connection.
• Missing optional event values do not crash the widget.
• Multiple placed copies preserve independent field overrides.
• Refreshing the overlay does not lose required bounded state.
• Script failures appear with useful package context.
• Themes modify only documented themeable fields.
• Native SheevChat widgets remain unchanged after install.
• Preview images or videos show the actual widget.
• The changelog identifies compatibility or permission changes.

AI Prompt Template

Create, verify, correct, expand, and/or finish a SheevChat overlay widget package using the authoritative widget/API documentation supplied by the user.

Use the SheevChat Overlay Widget Developer Wiki:
https://sheevchat.com/overlay-widgets

First classify the deliverable:
- widget_pack for new visual/runtime behavior
- theme_pack for appearance-only changes
- action_library for app connections and callable controls
- community_pack for transparent dependencies and optional disabled recipes
- chat_game for declarative command games using `sheevchat-chat-game-v2`

Map the target documentation into SheevChat concepts before writing files. For an action library identify its connection, authentication, actions, fields, dynamic sources, event subscriptions, response ingestion, and capabilities. For a widget or theme identify its provider or target, editable fields, defaults, previews, dependencies, events, and capabilities. If the documentation requires unsupported behavior, put it in an "unsupported gaps" section instead of inventing schema or runtime APIs.

Hard rules:
- Do not use the deprecated overlay_pack type.
- Keep widget behavior, themes, app control, and recipes in separate package types.
- Never mutate SheevChat built-in widget fields or behavior from a third-party package.
- Use provider streamelements only for a real StreamElements custom-widget compatibility export.
- Use provider sheevchat only for a SheevChat-owned native renderer.
- Use only the documented `sheevchat-widget-v1` and `sheevchat-theme-v1` APIs; do not invent bridge methods or data fields.
- A `sheevchat-widget` package must include a valid package-local HTML entry. Declare only the subscriptions it consumes, or mark an intentionally event-free widget as static.
- A built-in theme renderer consumes parent-fed `settings`, `frame`, and `data`; it must not open SheevChat/platform sockets or take over app behavior.
- Route interactive widget buttons/actions through `widget-button` or `widget.action`; treat optional JSON as untrusted input.
- Declare only required capabilities and dependencies.
- Keep all package paths relative, traversal-safe, and inside the package.
- Chat games use schema version 2, contain no executable content, and keep optional visuals in a separate companion widget.
- Never store secrets in fieldData, assets, widget state, or package metadata.
- Themes change only declared themeable fields and contain no hidden runtime behavior.
- Handle missing optional event values safely.
- Include useful preview metadata, version compatibility, and a changelog.

Before output, verify the package type, provider lane, required files, capability list, dependency graph, trust implications, asset paths, event listeners, editable fields, defaults, theme targets, sample-data behavior, and current runtime support.

Return the complete package file tree and the exact contents of every text manifest/source file. Include a short in-app test plan. Clearly label anything outside the active widget/theme v1 contracts or chat-game v2 contract as an unsupported gap.

Current Limitations

• Arbitrary third-party JavaScript does not run inside native SheevChat widget renderers.
• Unknown providers render safe placeholders.
• sheevchat-widget-v1 is active, but future event names and bridge additions are not available until documented.
• Imported StreamElements compatibility is bounded and does not guarantee every undocumented browser or platform behavior.
• Widgets do not receive every field from every streaming platform.
• Theme packs cannot change moderation, filtering, command processing, network behavior, or action execution.
• Community recipes should be previewed and disabled by default until the user opts in.
• Marketplace monetization and paid-theme rules remain outside this developer contract until legal and payment review is complete.
• Paid checkout, entitlements, subscription gates, ratings, creator payouts, and creator-fund rankings are not active.
• There is no public package upload/submission portal with automated review.
• Remote webhook triggers that require SheevChat servers are not available.
• SheevChat does not promise full StreamElements API parity or automatic native conversion of every imported widget.
• Free local imports do not require a promised marketplace account system.
• Third-party developers cannot bypass iframe isolation through a stable native renderer SDK.