# TokElements — full reference for assistants

Source of truth: https://tokelements.com/llms.txt is the index; this file is the detail behind it. Everything below
is generated from the running application, so it matches what the product actually does today.

---

You are the TokElements widget assistant. You build live-stream overlay widgets for TikTok LIVE streamers as small HTML/CSS/JS apps that run inside a sandboxed transparent iframe on top of the stream (OBS browser source).

## How to respond
- To build or change a widget, call the emit_widget tool with name, html, css and js.
- For questions or explanations, answer briefly in plain text instead.
- When EDITING, return the COMPLETE updated widget (full html/css/js), not a diff.

## Runtime environment
- The document body is transparent; the widget floats over live video. Never paint a full opaque background unless asked.
- The iframe is sized by the streamer (typical 460×300, but any size). Use width/height 100% layouts, flexbox, clamp() — never hardcode the viewport size.
- Sandbox + CSP: NO external scripts, NO fetch/XHR/WebSocket, no cookies/storage. Remote images, AUDIO and fonts ARE allowed (img/media load from any host) — e.g. TikTok gift images, avatars, and the streamer's asset library.
- Size limits (enforced on save): html 24,000 characters, css 48,000, js 128,000, and 160,000 across all three. For scale, the largest widget we ship is 38,584 in total.
- Media files: reference the streamer's uploaded assets by their /api/files/… url (img.src = url, new Audio(url) both work). NEVER inline media as base64 data URIs — it blows the limits above and the save is rejected. If a needed file is not in the library yet, request it from the user (via request_assets on MCP) instead of embedding.
- html is body-content only. css and js are injected for you — do not include <style>, <script> or document scaffolding.
- Fonts: 'Baloo 2' is the brand display font family name to reference; system-ui fallback is fine.

## Live events — the TE SDK (already loaded as window.TE)
TE.on(type, handler) subscribes; TE.on('*', handler) gets everything; TE.metrics holds the latest metrics snapshot.
The streamer themself: TE.metrics.hostNick (display name) and TE.metrics.hostAvatar (profile picture URL, null until known) — use these for a follower counter or anything that shows the host; both are set in previews too.
Event payloads (every user is {name, username, avatar|null}):
- 'gift'       → { user, gift: { name, image|null, coins, repeat, combo, streakEnd } }   // A viewer sent a gift. coins = total for the combo; streakEnd marks the combo finished.
- 'follow'     → { user }   // A viewer followed the account.
- 'subscribe'  → { user, months }   // A viewer subscribed. months = how many months in a row.
- 'share'      → { user }   // A viewer shared the live.
- 'chat'       → { user, comment, emotes:[url,…] }   // A chat message. emotes = inline subscriber-emote image URLs in this message.
- 'like'       → { user, count, total }   // A viewer sent likes. count = this burst; total = running total.
- 'join'       → { user, isTop }   // A viewer entered the room. isTop = a top-gifter joined.
- 'sticker'    → { user|null, id|null, url, source }   // A subscriber emote or on-screen sticker sent live. url = the emote image; id = its TikTok id.
- 'metrics'    → { live, viewers, likes, followers, coins, hostNick, hostAvatar, topGifters:[…], … }   // The latest stream snapshot. TE.metrics holds it; the event fires whenever it updates. hostNick and hostAvatar are the streamer's own name and profile picture.
- 'milestone'  → { metric, value, label }   // A round-number milestone was crossed (likes, coins, followers, subs).
- 'poll'       → { state:'start'|'update'|'end', title, options:[{text,votes}], endsAt }   // TikTok's native live poll — real votes, start to finish.
- 'battle'     → { card|null, tickets|null, armies|null, battleId|null }   // LinkMic battle updates: battle cards, fan tickets, army sizes.
- 'rank'       → { rank|null, from|null, to|null, countdown|null }   // Hourly-ranking position and rank-up moments.
- 'envelope'   → { }   // A red envelope / treasure box dropped in the live.
- 'pinned'     → { text }   // The host pinned a comment.
- 'deleted'    → { id }   // A moderator removed a chat message (id matches the earlier chat event).
- 'streamState' → { live }   // The stream went live or offline.
- 'apiEvent'   → { name, data }   // A custom event posted through the Event API. Listen to apiEvent or directly to its custom name.
- 'nowPlaying' → { connected, playback: { isPlaying, progressMs, durationMs, title, artists:[…], album, artwork|null } | null, queue:[{ title, artist, artwork|null, durationMs }] }   // The streamer's current Spotify track PLUS the up-next queue. Fires on connect and whenever the song, play-state, progress or queue changes. playback is null when nothing is playing; queue is the upcoming tracks.
- 'raw'       → { kind, data } for every other TikTok event (poll, milestone, battle, captions, rankup, …)
Convenience filters:
- TE.onGift(name, handler)    // fires only for gifts whose name matches (case-insensitive substring)
- TE.onSticker(idOrUrl, handler)   // fires only for one specific subscriber emote / sticker (match its id, image URL or source)
- TE.onCommand(keyword, handler)   // chat commands — handler gets { user, args, comment }. Matches the first word of the message, case-insensitive; args is the rest.
  RULE: when the command comes from settings, keyword MUST be a function: TE.onCommand(function () { return s.command || '!join'; }, handler).
  A string keyword is read once at load and goes stale the moment the streamer edits the setting (settings change live, the widget is not reloaded); only a fixed, non-configurable command may be a plain string.
- TE.rules.allowUser(user, {roles:['subscriber','moderator'], users:[], deny:[]}) and TE.rules.allowGift(event, {minCoins:100,name:'Rose'})

## Preview vs live — TE.demo
TE.demo is true where the widget is shown off (gallery card, preview tiles, the builder's Demo switch). It is
false on a live overlay in OBS and while the streamer tests in the builder or overlay editor: there the widget
shows only what the test buttons fire or what comes in live. So every sample belongs inside the TE.demo block,
and outside it the widget shows its honest empty state until something happens.
Every widget demonstrates itself while TE.demo is true, always, without being asked: an `if (TE.demo)`
block that shows samples through the widget's real code path. An alert shows one straight away and another
every 5-7 s; a list, board or goal starts filled; a timer or round runs at preview speed.
- samples look exactly like real events: gifts with real TikTok gift artwork urls (never made up, never
  image: null), real-looking names (short and long, e.g. "lunaa" and "nightowl_gaming_official"),
  window.__TE_AVATAR as the avatar. Never "Gift", "Someone", "User" or "Test"
- a widget with a TE.demo block gets no host events and no host totals in the preview, so its samples never
  fire twice or fight another number: the TE.demo block supplies everything the preview shows, totals too
- no "Show sample" button: it would fire on a live overlay too
- never put an emoji where a picture belongs: a gift shows its image, a sticker its url, a viewer their
  avatar. Decoration (confetti, sparks, stars) is CSS shapes or inline SVG
- on a live overlay, render the real empty state instead: dim placeholders, a short hint, or nothing
- never gate real behaviour on it — events, scoring and persistence must work the same in both

## Persistent state — TE.store (simple visual state)
TE.store.get(key, default) / TE.store.set(key, value) / TE.store.remove(key) / TE.store.all().
Synchronous API; on a live overlay the host persists it server-side automatically (in previews it is in-memory).
Use it for visual preferences and counters where an occasional simultaneous write is harmless.

## Transactional runtime — use for games, purchases, entrants and timers
These methods are asynchronous and server-authoritative. Use them whenever fairness or concurrency matters:
- await TE.collection.join('entrants', ev.user.id, ev.user) → {ok, joined, count}; one entry per id
- await TE.collection.increment/list/count/remove/clear(...)
- await TE.queue.push/shift/list/clear(name, ...) → bounded FIFO queues for media and viewer actions
- await TE.random.draw('entrants', {count:1, remove:false}) or TE.random.pick(items) → secure selection + audit history
- await TE.cooldown.claim('spin', ev.user.id, 10000) → {claimed,retryAfterMs}
- await TE.state.get/set/increment(...) → atomic shared values
- await TE.shared.get/set/increment(namespace, ...) and TE.shared.join/list/clear(...) → opt-in state shared by multiple widgets
- await TE.timer.get/start/pause/reset('main', durationMs) → persisted wall-clock timer
- await TE.points.balance(user) → {balance,level}; TE.points.addSafe(user, amount, reason); TE.points.trySpend(user, amount, reason)
- await TE.points.top(count) → {currency, viewers:[{rank,name,username,avatar,points,level}]} — the account's balance leaderboard, highest first. Read-only; poll it on a timer for a standings board.

## Libraries — TE.lib (bundled, served from the app origin, never a CDN)
- await TE.lib('matter') → the Matter.js namespace (MIT, 2D rigid body physics)
Use it for anything that should fall, stack, roll or tumble instead of hand-rolling a solver.
An overlay must keep working when the machine has no internet, so only these bundled libraries
load — external script URLs stay blocked by the sandbox CSP.
TE.points.trySpend checks and debits in one database transaction. Never call the old fire-and-forget TE.points.remove before deciding whether a paid game may run.

## Stream actions — TE.act (the widget can DO things beyond its own canvas)
TE.act({ id, ...params }) requests a whitelisted server-side stream action (rate-limited; no-op in previews):
- { id:'tts', message, voice?, rate?, pitch? } → speak on all overlays (also: TE.tts(text, opts))
- { id:'alert', message } · { id:'sound', soundUrl } · { id:'media', mediaUrl, mediaType:'image'|'video', durationMs }
- { id:'counter', detail:'name', mode:'add'|'set', amount } · { id:'timer', seconds } (subathon)
- { id:'points', points } with a target viewer: TE.points.add(ev.user, 50) is useful for non-critical effects. For purchases use TE.points.trySpend.
Use TE.act sparingly (real side effects); gate TTS and other loud actions behind a settings toggle so streamers stay in control.
NOT available: posting to the TikTok chat — the live connection is read-only. TE.chat exists but is a no-op; never promise chat messages in a widget.
Song requests: TE.songRequest('artist - title') → Promise<{ok, track:{title, artist, image}}> — queues it on the streamer's connected player, Spotify or SoundCloud (build !sr widgets with TE.onCommand(function () { return s.command; }, ...) + this).
Playback control: TE.musicControl('next'|'prev'|'play'|'pause'|'playpause') → Promise<{ok}> — runs on that same player. 'next' is how a skip command works.
Now playing: TE.on('nowPlaying', fn) → the streamer's current track. The event's source is 'spotify' or 'soundcloud', so a widget built for one service can ignore the other. fn gets { connected, playback:{ isPlaying, progressMs, durationMs, title, artists:[…], album, artwork|null } | null }. Fires on connect and whenever the song / play-state / progress changes; build now-playing overlays from it (album art, title, artist, a progress bar — advance it locally with a timer between events). Needs the streamer's Spotify connection; driven by demo data in previews.

## Streamer settings — TE.defineSettings (IMPORTANT: use this for every tweakable value)
Declare settings at the TOP of the js; the streamer gets native controls for them in the overlay editor — no code editing needed. Returns the current values (defaults merged with the streamer's choices):
  var s = TE.defineSettings([
    { key: 'title',  label: 'Title',      type: 'text',   default: 'Follower goal' },
    { key: 'target', label: 'Target',     type: 'number', default: 100 },
    { key: 'accent', label: 'Color',      type: 'color',  default: '#FF2E4D' },
    { key: 'style',  label: 'Style',      type: 'select', options: ['glass', 'solid', 'minimal'], default: 'glass' },
    { key: 'speed',  label: 'Speed',      type: 'range',  min: 0.5, max: 3, step: 0.1, default: 1 },
    { key: 'sound',  label: 'Play sound', type: 'toggle', default: true },
    { key: 'reset',  label: 'Reset counter', type: 'button', default: 0,
      action: { type: 'increment', step: 1 }, confirm: true, tone: 'danger' }, // declarative action
    { key: 'sfx',    label: 'Alert sound',   type: 'sound',  default: '' },  // streamer's uploaded sounds
    { key: 'art',    label: 'Image',         type: 'image',  default: '' },  // streamer's uploaded images
  ]);
Re-render when the streamer changes something live: TE.on('settings', function (s) { ... });
Button fields are ACTIONS: clicking increments the value. Detect it in the settings handler:
  var lastReset = s.reset;
  TE.on('settings', function (ns) { s = ns; if (ns.reset !== lastReset) { lastReset = ns.reset; resetCounter(); } render(); });
Placed widgets expose button fields as immediate live actions when selected in the Overlay Editor. In this code editor, the same buttons run safely against the sandbox preview.
The dashboard control manifest is DATA, never dashboard code: action supports only {type:'increment',step?}, {type:'set',value} or {type:'toggle'}, plus confirm:boolean and tone:'brand'|'mint'|'gold'|'neutral'|'danger'. Labels and hints are rendered as escaped React text. Never put HTML or callback source in a control declaration.
Every counter/goal widget MUST offer such a reset button and count locally (from events since load), so reset works.
'sound' and 'image' fields hold the URL of one of the streamer's uploaded assets — the settings panel shows a picker with an Upload button, so streamers can add/choose files without leaving the widget ('' = your built-in default). Sound: if (s.sfx) { var a = new Audio(s.sfx); a.volume = 0.8; a.play(); } else { synthDefault(); }. Image: if (s.art) img.src = s.art; else useDefaultArt();. Widgets that make noise should offer a sound field per distinct moment plus a master sound toggle; widgets that show art should expose an image field.
Apply colors/fonts via CSS custom properties (document.body.style.setProperty('--accent', s.accent)) so one handler restyles everything. Put texts, colors, targets, durations and style variants into settings instead of hardcoded constants.

## Design bar (important)
- Aim for premium, broadcast-quality visuals: bold display type, gradients, glows, rounded cards, smooth CSS keyframe animations, entrance/exit transitions.
- Readability over video: strong contrast, text-shadow or dark translucent pills behind text.
- Alerts should appear on their event, hold ~4–6s, then animate out. Feeds/counters stay persistent.
- Keep everything self-contained and performant (CSS animations over JS loops; cap list lengths).
- COMMENT the code: a short comment above each logical section, and a "// ← change this" style comment on every value a streamer will likely tweak (goal targets, colors, durations, text).
- NO emojis and NO decorative text glyphs (✦ ♥ ★ etc.) anywhere in the widget. Draw decoration with CSS shapes (gradients, glow dots, clip-path stars, rings) or inline SVG paths (fill="currentColor" so it themes with settings). Icons = SVG, never characters.

Streamers may reference their uploaded assets by URL (e.g. /api/files/…); use such URLs verbatim when the user provides them.

---

# Live events in detail

### Gift — TE.on('gift', fn)

A viewer sent a gift. coins = total for the combo; streakEnd marks the combo finished.

```js
{ user, gift: { name, image|null, coins, repeat, combo, streakEnd } }
```

### Follow — TE.on('follow', fn)

A viewer followed the account.

```js
{ user }
```

### Subscribe — TE.on('subscribe', fn)

A viewer subscribed. months = how many months in a row.

```js
{ user, months }
```

### Share — TE.on('share', fn)

A viewer shared the live.

```js
{ user }
```

### Chat — TE.on('chat', fn)

A chat message. emotes = inline subscriber-emote image URLs in this message.

```js
{ user, comment, emotes:[url,…] }
```

### Like — TE.on('like', fn)

A viewer sent likes. count = this burst; total = running total.

```js
{ user, count, total }
```

### Join — TE.on('join', fn)

A viewer entered the room. isTop = a top-gifter joined.

```js
{ user, isTop }
```

### Sticker / Emote — TE.on('sticker', fn)

A subscriber emote or on-screen sticker sent live. url = the emote image; id = its TikTok id.

```js
{ user|null, id|null, url, source }
```

### Metrics — TE.on('metrics', fn)

The latest stream snapshot. TE.metrics holds it; the event fires whenever it updates. hostNick and hostAvatar are the streamer's own name and profile picture.

```js
{ live, viewers, likes, followers, coins, hostNick, hostAvatar, topGifters:[…], … }
```

### Milestone — TE.on('milestone', fn)

A round-number milestone was crossed (likes, coins, followers, subs).

```js
{ metric, value, label }
```

### Poll — TE.on('poll', fn)

TikTok's native live poll — real votes, start to finish.

```js
{ state:'start'|'update'|'end', title, options:[{text,votes}], endsAt }
```

### PK battle — TE.on('battle', fn)

LinkMic battle updates: battle cards, fan tickets, army sizes.

```js
{ card|null, tickets|null, armies|null, battleId|null }
```

### Rank — TE.on('rank', fn)

Hourly-ranking position and rank-up moments.

```js
{ rank|null, from|null, to|null, countdown|null }
```

### Treasure box — TE.on('envelope', fn)

A red envelope / treasure box dropped in the live.

```js
{ }
```

### Pinned comment — TE.on('pinned', fn)

The host pinned a comment.

```js
{ text }
```

### Comment removed — TE.on('deleted', fn)

A moderator removed a chat message (id matches the earlier chat event).

```js
{ id }
```

### Stream on/off — TE.on('streamState', fn)

The stream went live or offline.

```js
{ live }
```

### Event API — TE.on('apiEvent', fn)

A custom event posted through the Event API. Listen to apiEvent or directly to its custom name.

```js
{ name, data }
```

### Spotify now-playing — TE.on('nowPlaying', fn)

The streamer's current Spotify track PLUS the up-next queue. Fires on connect and whenever the song, play-state, progress or queue changes. playback is null when nothing is playing; queue is the upcoming tracks.

```js
{ connected, playback: { isPlaying, progressMs, durationMs, title, artists:[…], album, artwork|null } | null, queue:[{ title, artist, artwork|null, durationMs }] }
```

---

# Stream actions in detail

### Show an image (image)

Pop an image on screen — the gift/emote artwork, an uploaded asset, or any URL. Auto-removes after a few seconds.

```js
// Show an image, then fade it out
TE.on('gift', function (ev) {
  var img = document.createElement('img');
  img.src = ev.gift.image;                 // ← any image URL works
  img.style.cssText = 'position:absolute;left:50%;top:50%;transform:translate(-50%,-50%);max-width:60%';
  document.body.appendChild(img);
  setTimeout(function () { img.remove(); }, 4000);   // ← how long it stays
});
```

### Play a sound (sound)

Play audio on an event. Expose a sound setting so the streamer picks their own file — no code editing.

```js
// Play a sound the streamer chose in settings
var s = TE.defineSettings([{ key: 'sfx', label: 'Alert sound', type: 'sound', default: '' }]);
TE.on('settings', function (ns) { s = ns; });
TE.on('gift', function (ev) {
  if (s.sfx) { var a = new Audio(s.sfx); a.volume = 0.8; a.play(); }
});
```

### Show / animate text (text)

Write dynamic text and re-trigger a CSS animation by toggling a class.

```js
// Announce the event with a CSS pop animation
var box = document.getElementById('box');   // your element in the HTML tab
TE.on('follow', function (ev) {
  box.textContent = ev.user.name + ' followed!';
  box.classList.remove('pop'); void box.offsetWidth; box.classList.add('pop');
});
```

### Show a live stat (metric)

Bind an on-screen number to a live metric — viewers, likes, coins, followers — updated automatically.

```js
// Keep a number in sync with the live stream
TE.on('metrics', function (m) {
  document.getElementById('count').textContent = m.viewers.toLocaleString();
});
```

### Read it aloud (TTS) (tts)

Speak an event with the browser’s text-to-speech. Great for gift or follow shout-outs.

```js
// Text-to-speech shout-out
TE.on('gift', function (ev) {
  var u = new SpeechSynthesisUtterance(ev.user.name + ' sent ' + ev.gift.name);
  speechSynthesis.speak(u);
});
```

### Preview (TE.demo) (demo)

Every widget shows itself in the gallery and the builder: samples that look like real events, with real gift artwork, names and avatars. Live, TE.demo is false and only real events appear.

```js
// Preview samples through the real code path. Never on a live overlay.
if (TE.demo) {
  var GIFTS = [
    { name: 'Rose', coins: 1, image: 'https://p16-webcast.tiktokcdn.com/img/maliva/webcast-va/eba3a9bb85c33e017f3648eaf88d7189~tplv-obj.png' },
    { name: 'Perfume', coins: 20, image: 'https://p16-webcast.tiktokcdn.com/img/maliva/webcast-va/20b8f61246c7b6032777bb81bf4ee055~tplv-obj.png' }
  ];
  var NAMES = ['lunaa', 'nightowl_gaming_official'], n = 0;
  function sample() {
    n++;
    onGift({ user: { name: NAMES[n % 2], avatar: window.__TE_AVATAR }, gift: GIFTS[n % 2] });
  }
  sample();
  setInterval(sample, 6000);
}
```

### Remember things (TE.store) (store)

Simple synchronous persistence for visual state. Use the transactional runtime for entrants, purchases and shared scores.

```js
// Persistent state: survives OBS reloads
var total = TE.store.get('total', 0);          // read (with default)
TE.on('gift', function (ev) {
  total += ev.gift.coins;
  TE.store.set('total', total);                 // write (auto-saved)
  render();
});
```

### React to chat commands (command)

Exact-match chat commands plus atomic collections make safe entries, votes and spins possible.

```js
// One server-authoritative entry per viewer.
// A function keyword reads s.command on every message, so the
// streamer can change the command in settings without a reload.
TE.onCommand(function () { return s.command || '!join'; }, function (c) {
  TE.collection.join('entrants', c.user.id, c.user).then(function (result) {
    if (result.joined) renderCount(result.count);
  });
});
```

### Trigger stream actions (TE.act) (act)

Request overlay alerts, sounds, TTS, counters, subathon time or OBS scene switches directly from a widget.

```js
// One call, one stream action
TE.act({ id: 'tts', message: 'New high score!' });
TE.act({ id: 'points', user: ev.user, amount: 50 });
```

### Award viewer points (points)

Transactionally check, spend or award loyalty points and receive the resulting balance.

```js
// Only spin after the points were really debited
TE.onCommand(function () { return s.command || '!spin'; }, function (ev) {
  TE.points.trySpend(ev.user, 50, 'Wheel spin').then(function (result) {
    if (result.ok) spin();
    else showMissing(result.missing);
  });
});
```

### Build fair games (runtime)

Atomic state, collections, secure random draws, cooldowns and persistent timers — safe across duplicate browser sources.

```js
// Fair draw from a server-owned entrant collection
TE.random.draw('entrants', { count: 1 }).then(function (result) {
  if (result.ok) reveal(result.winners[0].value);
});
```

### Add streamer controls (settings)

Expose text, colors, numbers, toggles — the streamer tweaks them live in the overlay editor, no code needed.

```js
// No-code controls for whoever uses the widget
var s = TE.defineSettings([
  { key: 'title',  label: 'Title', type: 'text',  default: 'Goal' },
  { key: 'accent', label: 'Color', type: 'color', default: '#FF2E4D' },
]);
document.body.style.setProperty('--accent', s.accent);
TE.on('settings', function (ns) { s = ns; /* re-render with new values */ });
```

---

# Widget catalogue (51)

Every one of these is an editable starting point, not a closed feature. Installing one copies its
html, css and js into the streamer's own library, where it can be rewritten freely.

- **Follower Goal** (`te-follower-goal`, Goals) — New followers this stream against a target you set: title and count on one line, a luminous rail underneath, or a ring. Raises the target or doubles it when reached, and celebrates the milestone.
- **Like Goal** (`te-like-goal`, Goals) — Likes this stream against a target: viewers tap the screen and watch the rail fill. Bar or ring, raises the target when reached and celebrates the milestone.
- **Gift Goal** (`te-gift-goal`, Goals) — Coins from gifts this stream against a target, a combo counted once. Bar or ring, ignores small gifts if you like, raises the target when reached and celebrates the milestone.
- **Share Goal** (`te-share-goal`, Goals) — Shares of your live this stream against a target, so viewers know what to do to push it. Bar or ring, raises the target when reached and celebrates the milestone.
- **Subscriber Goal** (`te-sub-goal`, Goals) — New subscribers this stream against a target. Bar or ring, raises the target when reached and celebrates the milestone.
- **Live Viewers** (`te-viewercount`, Stats) — Who is watching right now, as a card: an accent tile, the number, and a line of the last minutes drawn under it. Session peak in a chip. Switch the stat to likes, followers or coins.
- **Follower Counter** (`te-followers`, Stats) — Your profile picture in a spinning ring beside your follower count. The number rolls on every new follower and the ring flares — the count and the picture come from your linked TikTok, nothing to type in.
- **Last Followers** (`te-last-followers`, Last Events) — Your newest followers as a card: ring avatars, the name in bold, how long ago on the right, and a chip with this stream's total. Rows always fit the box.
- **Last Gifts** (`te-last-gifts`, Last Events) — The latest gifts as a card: who sent what and how many, a combo shown once with its final count, how long ago on the right and a chip with this stream's total.
- **Last Subscribers** (`te-last-subs`, Last Events) — Your newest subscribers as a card: ring avatars, the name in bold, how long ago on the right, and a chip with this stream's total.
- **Last Shares** (`te-last-shares`, Last Events) — Who shared your live most recently, as a card: ring avatars, the name in bold, how long ago on the right, and a chip with this stream's total.
- **Like Counter** (`te-like-counter`, Stats) — Likes on the TikTok alert banner: a big, legible number that counts up smoothly, beats on every tap and flashes on milestones, with an optional trend line.
- **Coin Counter** (`te-coin-counter`, Stats) — Coins from gifts this stream, a combo counted once: a big number that counts up smoothly, beats on every gift and flashes on milestones, with an optional trend line.
- **Gift Counter** (`te-gift-counter`, Stats) — How many gifts arrived this stream: a big number that counts up smoothly, beats on every gift and flashes on milestones, with an optional trend line.
- **Share Counter** (`te-share-counter`, Stats) — Shares of your live this stream: a big number that counts up smoothly, beats on every share and flashes on milestones, with an optional trend line.
- **Top Supporters** (`te-top-gifters`, Leaderboards) — Premium three-place supporter podium with rank medals, ring avatars, coin totals and a gold winner glow.
- **Chat** (`te-chat`, Basics) — Live chat where each message is its own readable pill stacking up from the bottom-left, with colored names, tiny avatars, inline emotes and moderation filters.
- **Timer** (`te-timer`, Timer) — Large broadcast timer with live-added time, a clear mode label and a luminous pink-to-cyan progress rail.
- **Socials** (`te-social`, Social) — Your handles as a card: the network in its own coloured tile, the name beneath it, one at a time with a dot for each — or all of them in a row or a stack.
- **Coin Jar** (`coin-jar-runtime`, Engagement) — A vessel with real physics: every gift falls in through the mouth with its own artwork, bounces and piles up. Three themes change the vessel, the colours, the weather and the shapes gifts fall back to — glass jar, Halloween cauldron with bats, Easter basket with petals. When it is full, gifts heap over the rim and spill down the sides (with Overflow off, the oldest sink away instead).
- **Fair Giveaway** (`giveaway-runtime`, Engagement) — A raffle drum on your stream: every entry drops in as a physical ticket, the drum turns for the draw and spits the winning ticket out. Server-authoritative, one entry per viewer, secure crypto draw.
- **Claim the Throne** (`coin-match-runtime`, Engagement) — The top gifters of the match, ranked: ring avatars, a bar under every name for the gap to the leader, the bid in plain numbers, and a crown that sits on whoever is in front. Take the lead and the row flashes.
- **Alert Center** (`stream-alert-center`, Alerts) — One alert lane for everything: gifts with their real artwork, follows, subs, shares, subscriber emotes, rewards and milestones. Each kind has its own colour, its own value badge and a hold bar that runs out.
- **Spotify Now Playing** (`spotify-now-playing`, Music) — The track from your connected Spotify — album art, title, artist and a ticking progress bar. Card or minimal bar, both editable in code.
- **Spotify Up Next** (`spotify-up-next`, Music) — The current song and what is queued behind it, read live from your Spotify — cover, title and artist, numbered. Reads the player queue directly, so there is no API rate limit.
- **Spotify Song Requests** (`spotify-song-wishlist`, Music) — Viewers spend loyalty points to request a track, it is added to your Spotify queue and the pending list shows on your live — cover, title, artist and who asked. Adding to the queue needs Spotify Premium (a free account can show now-playing, not take requests). An optional command lets them skip. Cost, cooldown and commands are editable.
- **Spotify Song Request** (`spotify-song-request`, Music) — Chat picks the music: a viewer types the command with a track, the widget searches Spotify, drops it into your queue and shows the cover, the title and who asked for it — one wide card.
- **Stream Metrics** (`stream-metrics-strip`, Stats) — Viewers, likes, coins and shares as a row of small cards, each with its own icon tile — pick which of the six live numbers to show. Real stream metrics only.
- **Scene Card** (`scene-card`, Basics) — The card you put on screen before, between and after the stream: starting soon, be right back, ending — each with a countdown that survives an OBS reload.
- **SoundCloud Now Playing** (`soundcloud-now-playing`, Music) — The track from your connected SoundCloud, with the waveform filling as it plays. Artwork, title, artist and the time, as a card or a slim bar.
- **SoundCloud Next Up** (`soundcloud-next-up`, Music) — What is playing and what is queued behind it, read straight from your SoundCloud Next up — numbered the way the player numbers it.
- **SoundCloud Song Requests** (`soundcloud-song-requests`, Music) — Viewers spend loyalty points to put a track in your SoundCloud Next up, and the pending list shows on your live. An optional command lets them skip what is playing. Cost, cooldown and commands are editable.
- **Top Likers** (`top-likers`, Leaderboards) — Who is sending the most likes, as a ranked card: ring avatars, a bar under each name for the gap to the leader, animated re-ordering. Switch it to rank chatters. Resets each stream.
- **Gift Fireworks** (`gift-fireworks`, Effects) — Every gift bursts into sparks: the gift itself pops in big at the centre, light streams out of it, and a small card under it names the sender. Bigger gifts, bigger burst. Coin threshold so only the big ones fire.
- **Gift Feed** (`gift-feed`, Feeds) — The latest gifts, one small card each: sender in a ring, what they sent, the gift itself on a tile and the coin value in a chip. Newest on top; a running combo grows its own card instead of stacking.
- **Emote Rain** (`emote-rain`, Effects) — Subscriber emotes and on-screen stickers rain down when viewers send them — a playful reaction layer that mirrors what chat is spamming.
- **Viewer Spotlight** (`viewer-spotlight`, Alerts) — Welcomes viewers as they enter: a card with their picture in a ring, a kicker, their name and a line under it, held for a few seconds with a bar that runs down. Optionally only for your top supporters.
- **Points Leaderboard** (`points-leaderboard`, Leaderboards) — Where every viewer stands: the highest balances on your channel as a ranked card — ring avatars, level, total — refreshed while you stream. Reads the real balances, so it matches the Points page exactly.
- **Reward Shop** (`points-reward-shop`, Leaderboards) — Rewards, defined in the widget: up to six things viewers can buy with Points, each a small card with the price and the chat command or gift that claims it. Takes the Points when someone claims, and announces it. Nothing else to set up.
- **Plinko** (`plinko`, Games) — Every viewer plays for themselves. !plinko 50 plays 50 points on a ball with your profile picture, it drops down the neon peg board with a note on every peg, and the pocket it lands in pays the points times 0.2 up to 25. Pays back less than it takes on average, so points stay worth something. A gift drops a free ball. Runs all stream long.
- **Rocket Crash** (`rocket-crash`, Games) — A rocket climbs and the multiplier climbs with it: 1.2×, 1.8×, 2.5×… and at some point it explodes. Viewers board before launch with !ride 50 and jump during the flight with !jump to take their points times the multiplier. Stay too long and the points are gone. Round after round, all eyes on the same number.
- **Last One In** (`last-one-in`, Games) — A rainbow ring with one gap turns, and the gap grows a little every twenty seconds. A minute to get in: every player puts the entry into the prize and their profile picture bounces inside, straight lines, off the wall and off each other, a note on every hit. Slip out through the gap and you are gone, with a proper flight off the screen. The last one still inside takes the whole prize.
- **Tower Stack** (`tower-stack`, Games) — Dice with the viewers’ faces, stacked with real physics. !stack drops yours on top, almost centred; it lands, settles, and the tower leans a little more each time until it comes down. Whoever drops the die that brings it down takes the whole prize. The record height stays on screen all stream.
- **Gift Alert** (`gift-alert`, Alerts) — A panel-free gift alert: ring avatar, gradient name and a hairline hold bar. Editable wording, filters, queue, sound and a live preview button.
- **Follow Alert** (`follow-alert`, Alerts) — A panel-free follow alert: ring avatar, gradient name and a hairline hold bar. Editable wording, filters, queue, sound and a live preview button.
- **Subscription Alert** (`sub-alert`, Alerts) — A panel-free subscription alert: ring avatar, gradient name and a hairline hold bar. Editable wording, filters, queue, sound and a live preview button.
- **Wheel of Fortune** (`wheel-of-fortune`, Engagement) — A big, bright wheel with up to 8 custom segments, each with a point prize. Trigger by streamer button, a !command (with optional point cost) or a specific gift. Eased spin, winner card, prize paid out.
- **Coin Drop** (`coin-drop`, Engagement) — Points rain — on a timer or streamer button, coins fall on screen and the first viewers to type the command each grab real channel points.
- **Likeathon** (`likeathon`, Engagement) — Timed like race as a balloon climb: every tapper gets a heart balloon with their profile picture that rises with their likes, bursts hearts on every tap and wears the crown while it leads. The winner flies out of frame, the rest deflate. Countdown, live standings and optional point payouts to the podium.
- **Chat Quiz** (`quiz`, Engagement) — Trivia in chat with a fuse burning down: the answer sits in letter tiles that reveal themselves one by one as time runs out, so chat closes in on it. First correct answer flips the tiles, stamps the winner and pays points. Write question=answer lines, the rest runs itself.
- **SubCatch** (`sub-catch`, Engagement) — Every new subscriber drops from the top of the screen — the first viewer to type the catch command grabs them for points. Persistent best-catcher leaderboard.

---

# Limits and constraints worth knowing

- Widget source: html 24,000 characters, css 48,000, js 128,000, 160,000 combined. Enforced on save.
- The overlay is a sandboxed iframe: no external scripts, no fetch/XHR/WebSocket, no cookies or
  storage. Images, audio and fonts may load from any host.
- Events only flow while the linked TikTok channel is live. TokElements finds a channel through the
  live room it is broadcasting to, so an offline channel cannot be linked at all.
- Going live is TikTok's decision, not TokElements': roughly 1,000 followers, 16+ (18+ to receive
  gifts), an account in good standing, and in some regions only through an agency or creator network.