overlaify 0.0.0-stage → 0.1.0

package/lib/ws.js

@@ -0,0 +1,79 @@
+// Just enough WebSocket server for `overlaify dev`: the SDK in OBS connects to /api/live/:room and receives
+// action keys as text frames, the same protocol as the hosted LiveRoom. No dependencies, text frames only.
+import { createHash } from 'node:crypto';
+
+const GUID = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11';
+
+/** Completes the handshake for an HTTP 'upgrade' request. Returns a socket wrapper, or null if it isn't a WebSocket. */
+export function acceptWebSocket(req, socket, { onMessage, onClose }) {
+  const key = req.headers['sec-websocket-key'];
+  if (!key || (req.headers.upgrade || '').toLowerCase() !== 'websocket') {
+    socket.end('HTTP/1.1 400 Bad Request\r\n\r\n');
+    return null;
+  }
+  const accept = createHash('sha1').update(key + GUID).digest('base64');
+  socket.write(`HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\nConnection: Upgrade\r\nSec-WebSocket-Accept: ${accept}\r\n\r\n`);
+  socket.setNoDelay(true);
+
+  let buf = Buffer.alloc(0);
+  let closed = false;
+  const ws = {
+    send(text) { if (!closed) socket.write(frame(0x1, Buffer.from(text))); },
+    close() { if (!closed) { socket.write(frame(0x8, Buffer.alloc(0))); socket.end(); } }
+  };
+  const done = () => { if (!closed) { closed = true; onClose(ws); } };
+
+  socket.on('data', (chunk) => {
+    buf = Buffer.concat([buf, chunk]);
+    for (;;) {
+      const f = parse(buf);
+      if (!f) break;
+      buf = buf.subarray(f.length);
+      if (f.opcode === 0x1) onMessage(ws, f.payload.toString('utf8'));
+      else if (f.opcode === 0x9) socket.write(frame(0xA, f.payload));
+      else if (f.opcode === 0x8) { ws.close(); done(); return; }
+    }
+  });
+  socket.on('close', done);
+  socket.on('error', done);
+  return ws;
+}
+
+// One complete frame at the start of buf: { opcode, payload, length }, or null if more bytes are needed.
+// Client frames are always masked. Fragmented messages aren't supported; the SDK never sends them.
+function parse(buf) {
+  if (buf.length < 2) return null;
+  const opcode = buf[0] & 0x0f;
+  const masked = (buf[1] & 0x80) !== 0;
+  let len = buf[1] & 0x7f;
+  let at = 2;
+  if (len === 126) {
+    if (buf.length < 4) return null;
+    len = buf.readUInt16BE(2);
+    at = 4;
+  } else if (len === 127) {
+    if (buf.length < 10) return null;
+    len = Number(buf.readBigUInt64BE(2));
+    at = 10;
+  }
+  const mask = masked ? buf.subarray(at, at + 4) : null;
+  if (masked) at += 4;
+  if (buf.length < at + len) return null;
+  const payload = Buffer.from(buf.subarray(at, at + len));
+  if (mask) for (let i = 0; i < payload.length; i++) payload[i] ^= mask[i & 3];
+  return { opcode, payload, length: at + len };
+}
+
+function frame(opcode, payload) {
+  const len = payload.length;
+  const head = len < 126 ? Buffer.from([0x80 | opcode, len])
+    : len < 65536 ? Buffer.from([0x80 | opcode, 126, len >> 8, len & 0xff])
+      : Buffer.concat([Buffer.from([0x80 | opcode, 127]), bigLen(len)]);
+  return Buffer.concat([head, payload]);
+}
+
+function bigLen(n) {
+  const b = Buffer.alloc(8);
+  b.writeBigUInt64BE(BigInt(n));
+  return b;
+}

package/package.json

@@ -1,6 +1,16 @@
 {
   "name": "overlaify",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Build Twitch/OBS overlays that follow the Overlaify Overlay Spec: start from a template, validate, preview with simulated events and control them live.",
+  "type": "module",
+  "bin": { "overlaify": "bin/overlaify.js" },
+  "files": ["bin", "lib", "assets", "skill"],
+  "engines": { "node": ">=18" },
+  "scripts": {
+    "sync": "node scripts/sync.mjs"
+  },
+  "keywords": ["twitch", "obs", "overlay", "stream", "alerts", "browser-source", "claude", "skill"],
+  "homepage": "https://www.overlaify.com",
+  "repository": { "type": "git", "url": "git+https://github.com/overlaify/overlaify.git" },
+  "license": "MIT"
+}

package/skill/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: overlaify
+description: Build live-stream overlays for Twitch/OBS (alert boxes, chat boxes, goal bars, timers, counters, tickers, webcam frames, Starting soon / BRB scenes, chat-command effects) as single HTML files that follow the Overlaify Overlay Spec, then validate and preview them with the overlaify CLI. Use whenever someone wants a stream overlay, an OBS browser source, or to change one that already exists.
+argument-hint: "[describe the overlay you want]"
+---
+
+# Overlaify overlays
+
+An Overlaify overlay is one HTML file that runs as an OBS Browser Source (1920×1080, transparent). It gets
+Twitch events from the Overlaify SDK and declares its settings and live control keys in a JSON manifest.
+Following the spec is what makes it work in OBS, in `overlaify dev`, and on overlaify.com without changes.
+
+The full rules are in `references/overlay-spec.md`. Read it before writing your first overlay in a session.
+`examples/` has three overlays that pass the spec: an alert queue (`neon-alert.html`), a chat box
+(`chat-stack.html`) and a goal with settings and actions (`goal-bar.html`).
+
+## Workflow
+
+1. **Start the file.** Use `npx overlaify init <file>.html` for a blank starter (an alert with a manifest),
+   or `npx overlaify init <file>.html --template <slug>` to start from a library template
+   (`npx overlaify init --list` shows them). Pick the template closest to the request, then edit it.
+2. **Write the overlay** (rules below). Keep everything in the one file.
+3. **Validate** with `npx overlaify validate <file>.html`. Fix every error; fix warnings unless there is a
+   reason not to, and say what it is. Repeat until it passes.
+4. **Preview.** Suggest that the user run `npx overlaify dev <file>.html`. It is a long-running server, so
+   start it in the background if you run it yourself. It prints:
+   - a dev page with the preview, event buttons (follow, sub, gift, bits, raid, chat), the settings panel
+     and the action keys;
+   - an OBS URL (`http://localhost:4545/overlay`) to add as a Browser source at 1920×1080. It reloads
+     when the file is saved, and the action keys reach it live.
+   Tell the user to set their Twitch channel in the dev page's settings so real chat and events arrive.
+5. **Publish (only when the user asks).** `npx overlaify publish <file>.html --private` or `--public` puts it
+   on overlaify.com at `/<their username>/<name>` with a hosted OBS URL (`--name` sets the name). Ask the user which one they want; never pick for
+   them. Private: only they can open it on the site, but the OBS URL still works. Public: anyone with a link
+   can open and remix it, and it can be picked for the Overlaify Library. If it says they're not logged in,
+   ask them to run `npx overlaify login` (it opens a browser to approve). Publishing the same file again
+   adds a new version.
+6. **Start from an overlay on overlaify.com.** When the user names one (`<user>/<name>` or its page URL),
+   `npx overlaify download <user>/<name> [file]` saves it as a local file to change, then carry on from step 3.
+   A private one only downloads for its owner; if it says to log in, ask them to run `npx overlaify login`.
+
+If `npx` can't be used, the file still works: it loads the SDK from overlaify.com, so OBS can open it as a
+local file with `?channel=<twitch name>` added.
+
+## Rules that matter most
+
+- One self-contained HTML document, at most 80 KB. Inline all CSS and JS. Keep
+  `<script src="https://www.overlaify.com/sdk/v1/overlaify.js"></script>` in `<head>`; it is the only
+  external script. External files are limited to Google Fonts and Twitch emote images; draw everything else
+  with CSS, inline SVG, canvas or emoji.
+- `html, body { margin: 0; width: 1920px; height: 1080px; overflow: hidden; background: transparent; }`.
+  Paint a full-screen background only for full scenes (Starting soon, BRB).
+- Events come only from the SDK: `Overlaify.on('sub', fn)` and friends. There are no network calls, no
+  clicks and no dialogs; the overlay just runs.
+- Events look the same on every platform. For bits and other money, handle `tip` (show `e.display`, size
+  with `e.usd`), not `cheer`, which is Twitch-only; never both, or bits count twice.
+- For alerts, use `Overlaify.queue(handler)` so alerts never overlap.
+- Never insert viewer text as HTML. Use `textContent`, `Overlaify.escape()`, or
+  `Overlaify.renderMessage(text, emotes)` for chat with emotes.
+- Manifest in `<head>`: `<script type="application/json" id="overlaify-manifest">{ "spec": 1, ... }</script>`.
+  - Every customizable value is a **setting**, read with `Overlaify.param('key', <same default>)`.
+  - Every **action** has a handler, `Overlaify.action('name', fn)`. Add actions only for live state
+    (timers, counters, goals, queues, scenes): pause/resume, add/remove, reset with `"style": "danger"` and
+    `"confirm": true`.
+  - Never declare `channel`, `volume`, `mute` or `test`; the platform provides them.
+- Wrap `localStorage` in `try/catch` (the page runs sandboxed), and use it when an action's state should
+  survive an OBS refresh.
+
+## Making it look good
+
+Aim for a premium, hand-made overlay pack, not a generic template:
+- one clear visual idea;
+- a palette and type pairing that match the streamer's description;
+- motion with personality: an entrance, a subtle idle and an exit.
+
+Animate `transform` and `opacity`. Text must stay readable over busy gameplay and on phone screens: large
+sizes, strong contrast, an outline or shadow. Place things where streamers expect them unless asked
+otherwise:
+- alerts: top-center
+- chat: left edge
+- goal bars: top edge
+- tickers: bottom edge
+- webcam frames: a corner
+
+## Changing an existing overlay
+
+Edit the file in place and keep everything that wasn't asked to change. When behavior changes, update the
+manifest too (new settings, renamed actions), then validate again.

package/skill/examples/chat-stack.html

@@ -0,0 +1,68 @@
+<!doctype html>
+<html lang="en">
+<head>
+<script src="https://www.overlaify.com/sdk/v1/overlaify.js"></script>
+<meta charset="utf-8">
+<title>Glass Chat Stack</title>
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link href="https://fonts.googleapis.com/css2?family=Outfit:wght@400;600;800&display=swap" rel="stylesheet">
+<script type="application/json" id="overlaify-manifest">
+{
+  "spec": 1,
+  "settings": [
+    {"key": "max", "label": "Messages on screen", "type": "range", "default": 7, "min": 1, "max": 20, "step": 1, "desc": "Maximum number of messages on screen."},
+    {"key": "fade", "label": "Fade after", "type": "range", "default": 30, "min": 0, "max": 300, "step": 5, "unit": "s", "desc": "Seconds before a message fades out. 0 keeps messages until they are pushed off."},
+    {"key": "hidebots", "label": "Hide users", "type": "text", "default": "nightbot,streamelements,streamlabs", "desc": "Comma-separated usernames (lowercase, no spaces) whose messages are hidden."}
+  ],
+  "actions": [
+    {"name": "clear", "label": "Clear chat", "style": "danger", "wide": true}
+  ]
+}
+</script>
+<style>
+  html, body { margin: 0; width: 1920px; height: 1080px; overflow: hidden; background: transparent; }
+  #chat { position: absolute; left: 40px; bottom: 60px; width: 520px; display: flex; flex-direction: column; gap: 12px; }
+  .msg {
+    font-family: 'Outfit', system-ui, sans-serif; font-size: 26px; line-height: 1.35; color: #f4f1ff;
+    background: rgba(16, 13, 26, .72); backdrop-filter: blur(8px);
+    border-left: 5px solid var(--uc, #9b5cff); border-radius: 6px 16px 16px 6px;
+    padding: 12px 18px 14px; box-shadow: 0 8px 24px rgba(0,0,0,.35);
+    text-shadow: 0 1px 2px rgba(0,0,0,.6);
+    transform-origin: left bottom; animation: slide .35s cubic-bezier(.2,1.2,.4,1);
+    transition: opacity .6s, transform .6s;
+  }
+  .msg.gone { opacity: 0; transform: translateX(-40px); }
+  .who { font-weight: 800; color: var(--uc, #9b5cff); margin-right: 8px; }
+  .badge { display: inline-block; font-size: 15px; font-weight: 600; padding: 1px 8px; border-radius: 99px; margin-right: 6px; vertical-align: 3px; color: #0b0a10; }
+  .b-mod { background: #4dffa6; } .b-sub { background: #ffb547; } .b-vip { background: #ff4f8b; } .b-broadcaster { background: #ff6b4a; }
+  .bits { font-weight: 800; color: #c6ff3d; margin-left: 6px; }
+  @keyframes slide { from { opacity: 0; transform: translateY(20px) scale(.96); } }
+</style>
+</head>
+<body>
+<div id="chat"></div>
+<script>
+  const MAX = Overlaify.param('max', 7);
+  const FADE = Overlaify.param('fade', 30);          // seconds, 0 = never
+  const HIDE_BOTS = Overlaify.param('hidebots', 'nightbot,streamelements,streamlabs').split(',');
+  const box = document.getElementById('chat');
+
+  function remove(el) { el.classList.add('gone'); setTimeout(() => el.remove(), 600); }
+
+  Overlaify.on('chat', e => {
+    if (HIDE_BOTS.includes(e.user) || e.message.startsWith('!')) return;
+    const el = document.createElement('div');
+    el.className = 'msg';
+    el.style.setProperty('--uc', e.color || '#9b5cff');
+    const badges = [e.isBroadcaster && 'broadcaster', e.isMod && 'mod', e.isVip && 'vip', e.isSub && 'sub'].filter(Boolean)
+      .map(b => `<span class="badge b-${b}">${b === 'broadcaster' ? 'LIVE' : b.toUpperCase()}</span>`).join('');
+    el.innerHTML = `${badges}<span class="who">${Overlaify.escape(e.name)}</span>${Overlaify.renderMessage(e.message, e.emotes)}${e.bits ? `<span class="bits">◆ ${e.bits}</span>` : ''}`;
+    box.appendChild(el);
+    while (box.children.length > MAX) box.firstElementChild.remove();
+    if (FADE > 0) setTimeout(() => el.isConnected && remove(el), FADE * 1000);
+  });
+
+  Overlaify.action('clear', () => { box.replaceChildren(); });
+</script>
+</body>
+</html>

package/skill/examples/goal-bar.html

@@ -0,0 +1,89 @@
+<!doctype html>
+<html lang="en">
+<head>
+<script src="https://www.overlaify.com/sdk/v1/overlaify.js"></script>
+<meta charset="utf-8">
+<title>Liquid Goal Bar</title>
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link href="https://fonts.googleapis.com/css2?family=Space+Grotesk:wght@500;700&display=swap" rel="stylesheet">
+<script type="application/json" id="overlaify-manifest">
+{
+  "spec": 1,
+  "settings": [
+    {"key": "type", "label": "What to count", "type": "segmented", "default": "subs", "options": [{"value": "subs", "label": "Subs"}, {"value": "bits", "label": "Bits"}], "group": "Goal"},
+    {"key": "goal", "label": "Goal", "type": "number", "default": 50, "desc": "Defaults to 50 subs or 10,000 bits.", "group": "Goal"},
+    {"key": "start", "label": "Starting value", "type": "number", "default": 0, "desc": "E.g. subs you already have this month.", "group": "Goal"},
+    {"key": "label", "label": "Title", "type": "text", "default": "Sub goal", "group": "Look"},
+    {"key": "color", "label": "Fill color", "type": "color", "default": "#ff4f8b", "swatches": ["#ff4f8b", "#ffb547", "#c6ff3d", "#5ce1ff", "#a879ff"], "group": "Look"}
+  ],
+  "actions": [
+    {"name": "add", "label": "Add", "input": {"type": "number", "label": "Amount", "default": 1, "step": 1, "min": 1}},
+    {"name": "set", "label": "Set progress", "style": "secondary", "input": {"type": "number", "label": "Value", "default": 0, "step": 1, "min": 0}},
+    {"name": "reset", "label": "Reset to 0", "style": "danger", "confirm": true, "wide": true}
+  ]
+}
+</script>
+<style>
+  :root { --c: #ff4f8b; --c2: #ffb547; }
+  html, body { margin: 0; width: 1920px; height: 1080px; overflow: hidden; background: transparent; }
+  .wrap { position: absolute; left: 50%; top: 36px; transform: translateX(-50%); width: 900px; font-family: 'Space Grotesk', system-ui, sans-serif; color: #fff; }
+  .row { display: flex; justify-content: space-between; align-items: baseline; margin: 0 6px 10px; text-shadow: 0 2px 6px rgba(0,0,0,.7); }
+  .label { font-size: 28px; font-weight: 700; letter-spacing: .02em; }
+  .count { font-size: 26px; font-weight: 500; font-variant-numeric: tabular-nums; }
+  .track { position: relative; height: 34px; border-radius: 99px; background: rgba(12,10,20,.75); border: 2px solid rgba(255,255,255,.18); overflow: hidden; box-shadow: 0 6px 24px rgba(0,0,0,.4); }
+  .fill { position: absolute; inset: 0 auto 0 0; width: 0; border-radius: 99px;
+    background: linear-gradient(90deg, var(--c), var(--c2)); transition: width 1.2s cubic-bezier(.2,1,.3,1);
+    box-shadow: 0 0 20px var(--c); }
+  .fill::after { content: ''; position: absolute; inset: 0; border-radius: inherit;
+    background: repeating-linear-gradient(115deg, rgba(255,255,255,.22) 0 14px, transparent 14px 28px); animation: flow 1s linear infinite; }
+  .bump { animation: bump .5s; }
+  .done .fill { background: linear-gradient(90deg, #c6ff3d, #4dffa6); box-shadow: 0 0 28px #c6ff3d; }
+  @keyframes flow { to { background-position: 28px 0; } }
+  @keyframes bump { 40% { transform: scaleY(1.25); } }
+</style>
+</head>
+<body>
+<div class="wrap" id="w">
+  <div class="row"><span class="label" id="label"></span><span class="count" id="count"></span></div>
+  <div class="track" id="track"><div class="fill" id="fill"></div></div>
+</div>
+<script>
+  // ?type=subs|bits|follows  &goal=50  &start=0  &label=Sub%20goal  &color=%23ff4f8b
+  const TYPE = Overlaify.param('type', 'subs');
+  const GOAL = Overlaify.param('goal', TYPE === 'bits' ? 10000 : 50);
+  const KEY = `overlaify-goal-${Overlaify.channel}-${TYPE}-${GOAL}`;
+  const defaultLabel = { subs: 'Sub goal', bits: 'Bits goal', follows: 'Follower goal' }[TYPE] || 'Goal';
+  document.getElementById('label').textContent = Overlaify.param('label', defaultLabel);
+  document.documentElement.style.setProperty('--c', Overlaify.param('color', '#ff4f8b'));
+
+  let value = Overlaify.param('start', 0);
+  try { const saved = Number(localStorage.getItem(KEY)); if (saved > value) value = saved; } catch (e) {}
+
+  const fill = document.getElementById('fill'), count = document.getElementById('count'), track = document.getElementById('track');
+  function render(bump) {
+    const pct = Math.min(100, value / GOAL * 100);
+    fill.style.width = pct + '%';
+    count.textContent = `${value.toLocaleString()} / ${GOAL.toLocaleString()}`;
+    document.getElementById('w').classList.toggle('done', value >= GOAL);
+    if (bump) { track.classList.remove('bump'); void track.offsetWidth; track.classList.add('bump'); }
+    try { localStorage.setItem(KEY, String(value)); } catch (e) {}
+  }
+  function add(n) { if (n > 0) { const was = value < GOAL; value += n; render(true); if (was && value >= GOAL) Overlaify.chime('fanfare'); } }
+  Overlaify.action('add', n => add(Number(n) || 0));
+  Overlaify.action('set', n => { value = Math.max(0, Number(n) || 0); render(true); });
+  Overlaify.action('reset', () => { value = 0; render(true); });
+
+  if (TYPE === 'subs') {
+    Overlaify.on('sub', () => add(1));
+    Overlaify.on('gift', () => add(1));
+    // giftbomb is followed by individual 'gift' events from Twitch; count it only for simulations
+    Overlaify.on('giftbomb', e => e.simulated && add(e.count));
+  } else if (TYPE === 'bits') {
+    Overlaify.on('cheer', e => add(e.bits));
+  } else if (TYPE === 'follows') {
+    Overlaify.on('follow', () => add(1));
+  }
+  render(false);
+</script>
+</body>
+</html>

package/skill/examples/neon-alert.html

@@ -0,0 +1,84 @@
+<!doctype html>
+<html lang="en">
+<head>
+<script src="https://www.overlaify.com/sdk/v1/overlaify.js"></script>
+<meta charset="utf-8">
+<title>Neon Pulse Alerts</title>
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link href="https://fonts.googleapis.com/css2?family=Unbounded:wght@500;800&display=swap" rel="stylesheet">
+<script type="application/json" id="overlaify-manifest">
+{
+  "spec": 1,
+  "settings": [
+    {"key":"color","label":"Accent color","type":"color","default":"#c6ff3d","swatches":["#c6ff3d","#ff4f8b","#5ce1ff","#a879ff","#ffb547"],"desc":"Border, glow and kicker text."},
+    {"key":"duration","label":"Duration","type":"range","default":5,"min":2,"max":20,"step":0.5,"unit":"s","desc":"Seconds each alert stays on screen."}
+  ]
+}
+</script>
+<style>
+  :root { --c: #c6ff3d; --c2: #9b5cff; }
+  html, body { margin: 0; width: 1920px; height: 1080px; overflow: hidden; background: transparent; }
+  #stage { position: absolute; left: 50%; top: 120px; transform: translateX(-50%); }
+  .alert {
+    position: relative; min-width: 640px; padding: 34px 56px 38px; text-align: center;
+    font-family: 'Unbounded', system-ui, sans-serif; color: #fff;
+    background: rgba(10, 8, 18, .82); border-radius: 22px;
+    border: 3px solid var(--c);
+    box-shadow: 0 0 24px var(--c), inset 0 0 24px rgba(198,255,61,.25), 0 0 80px var(--c2);
+    opacity: 0; transform: scale(.6) translateY(-30px);
+  }
+  .alert.in { animation: pop .55s cubic-bezier(.2,1.6,.4,1) forwards; }
+  .alert.out { animation: leave .45s ease-in forwards; }
+  .kicker { font-size: 22px; font-weight: 500; letter-spacing: .32em; text-transform: uppercase; color: var(--c); text-shadow: 0 0 12px var(--c); }
+  .name { font-size: 64px; font-weight: 800; margin: 10px 0 6px; line-height: 1.05;
+    background: linear-gradient(90deg, #fff, var(--c), #fff); background-size: 200% 100%;
+    -webkit-background-clip: text; background-clip: text; color: transparent; animation: shine 1.6s linear infinite; }
+  .detail { font-size: 26px; font-weight: 500; color: #e9e4ff; }
+  .msg { margin-top: 14px; font: 500 22px system-ui, sans-serif; color: #cfc8e6; max-width: 760px; }
+  .ring { position: absolute; inset: -3px; border-radius: 22px; border: 3px solid var(--c); animation: ring 1.2s ease-out infinite; pointer-events: none; }
+  @keyframes pop { to { opacity: 1; transform: scale(1) translateY(0); } }
+  @keyframes leave { to { opacity: 0; transform: scale(.9) translateY(-40px); } }
+  @keyframes shine { to { background-position: -200% 0; } }
+  @keyframes ring { from { opacity: .9; transform: scale(1); } to { opacity: 0; transform: scale(1.12); } }
+</style>
+</head>
+<body>
+<div id="stage"></div>
+<script>
+  const accent = Overlaify.param('color', '#c6ff3d');
+  document.documentElement.style.setProperty('--c', accent);
+  const DURATION = Overlaify.param('duration', 5) * 1000;
+  const stage = document.getElementById('stage');
+  const esc = Overlaify.escape;
+  const tierLabel = t => t === 'prime' ? 'with Prime' : `Tier ${t}`;
+
+  function content(e) {
+    switch (e.type) {
+      case 'follow':   return ['New follower', e.name, 'welcome to the squad', '', 'pop'];
+      case 'sub':      return [e.months > 1 ? 'Resub' : 'New sub', e.name, `${tierLabel(e.tier)}${e.months > 1 ? ` · ${e.months} months` : ''}`, e.message, 'fanfare'];
+      case 'gift':     return ['Gifted sub', e.name, `→ ${e.recipientName || e.recipient}`, '', 'alert'];
+      case 'giftbomb': return ['Gift bomb', e.name, `${e.count} subs to the community!`, '', 'fanfare'];
+      case 'cheer':    return ['Cheer', e.name, `${e.bits.toLocaleString()} bits`, e.message, 'coin'];
+      case 'raid':     return ['Raid incoming', e.name, `with ${e.viewers.toLocaleString()} raiders`, '', 'fanfare'];
+    }
+  }
+
+  const enqueue = Overlaify.queue(async (e) => {
+    const c = content(e); if (!c) return;
+    const [kicker, name, detail, msg, sound] = c;
+    const el = document.createElement('div');
+    el.className = 'alert';
+    el.innerHTML = `<div class="ring"></div><div class="kicker">${esc(kicker)}</div><div class="name">${esc(name)}</div><div class="detail">${esc(detail)}</div>${msg ? `<div class="msg">${esc(msg)}</div>` : ''}`;
+    stage.appendChild(el);
+    requestAnimationFrame(() => el.classList.add('in'));
+    Overlaify.chime(sound);
+    await Overlaify.sleep(DURATION);
+    el.classList.add('out');
+    await Overlaify.sleep(450);
+    el.remove();
+  }, { gap: 400 });
+
+  ['follow', 'sub', 'gift', 'giftbomb', 'cheer', 'raid'].forEach(t => Overlaify.on(t, enqueue));
+</script>
+</body>
+</html>

package/skill/references/overlay-spec.md

@@ -0,0 +1,196 @@
+# Overlaify Overlay Spec — v1
+
+An Overlaify overlay is one HTML document that runs as an OBS Browser Source. Anything that follows this spec
+— written in Overlaify Studio, by another AI, or by hand — can be hosted on Overlaify, previewed with simulated
+events, configured from a settings panel and controlled live from a control page.
+
+The spec has three parts:
+
+1. **The document**: what the HTML file may contain.
+2. **The runtime**: the `Overlaify` SDK the overlay talks to, and the events it receives.
+3. **The manifest**: a JSON block in which the overlay declares its settings and live actions.
+
+`src/lib/validate.js` checks an overlay against this spec. Each rule below names the code it reports.
+**Errors** break the overlay on Overlaify and must be fixed. **Warnings** are quality problems.
+
+---
+
+## 1. The document
+
+| Rule | Code |
+|---|---|
+| One complete HTML document (`<!doctype html><html>…</html>`). | `not_html` (warning) |
+| A short overlay name in `<title>`. | `title_missing` (warning) |
+| At most 80 KB (80,000 bytes), so that Studio can still edit it. | `too_large` |
+| All CSS and JS inline. The one `<script src>` allowed is the SDK, `https://www.overlaify.com/sdk/v1/overlaify.js` (or `/sdk/v1/overlaify.js`), so the file also runs on its own; Overlaify replaces it with its own copy when hosting. | `external_script` |
+| No external files: stylesheets, images, audio, video, iframes, CSS `url()`/`@import`. The only hosts allowed are Google Fonts (`fonts.googleapis.com`, `fonts.gstatic.com`) and Twitch emotes (`static-cdn.jtvnw.net`). Use `data:` URLs, inline SVG, canvas or emoji instead. | `external_resource` |
+| No `<iframe>`, `<object>` or `<embed>`. | `embedded_frame` |
+| Other URLs in the code (outside tags) point only at those hosts. | `external_url` (warning) |
+| No network calls (`fetch`, `XMLHttpRequest`, `WebSocket`, `EventSource`): events come from the SDK. | `network_access` (warning) |
+| No user interaction or dialogs (`alert`, `confirm`, `prompt`): the overlay just runs. | `blocking_dialog` (warning) |
+
+Guidelines (not checked):
+
+- The canvas is 1920×1080. `html` and `body`: `margin: 0; width: 1920px; height: 1080px; overflow: hidden; background: transparent`.
+  Paint a full-screen background only for full scenes (Starting soon, BRB).
+- Never insert user text as raw HTML. Use `Overlaify.escape(str)` or `textContent`, and `Overlaify.renderMessage(text, emotes)` for chat with emotes.
+- Wrap `localStorage`/`sessionStorage` in `try/catch`: the page runs in a sandboxed, opaque origin.
+- Animate with `transform` and `opacity`. Keep text readable over gameplay (contrast, outline or shadow, large sizes).
+
+## 2. The runtime
+
+Overlaify injects the SDK before the overlay's own scripts, so a global `Overlaify` object is always there.
+Each spec version has its own SDK URL, `/sdk/v1/overlaify.js` for this one, so overlays written for it keep
+working when a later spec changes the runtime. `Overlaify.spec` is the version the loaded SDK implements.
+
+```
+Overlaify.on(type, handler)           subscribe; returns an unsubscribe function. '*' receives every event once.
+Overlaify.off(type, handler)
+Overlaify.queue(handler, { gap })     returns enqueue(event); runs handler one event at a time. handler may be
+                                      async or return ms to wait. Use it for alerts so they never overlap.
+Overlaify.param(key, fallback)        a setting's value; number and boolean fallbacks coerce the type.
+Overlaify.action(name, fn)            handle a manifest action; fn(value, event) gets the action's input value.
+Overlaify.dispatch(name, value?)      run an action from the overlay's own code (e.g. a chat command).
+Overlaify.escape(str)                 HTML-escape.
+Overlaify.renderMessage(text, emotes) safe HTML with Twitch emote <img class="ov-emote">.
+Overlaify.chime(kind, volume?)        built-in sound: 'alert' | 'pop' | 'coin' | 'fanfare' | 'low'. Respects mute.
+Overlaify.sleep(ms)                   Promise delay.
+Overlaify.simulate(type, overrides?)  emit a fake event (used by previews).
+Overlaify.channel                     Twitch channel login ('' in previews).
+Overlaify.sources                     the connected sources: [{ platform, channel, connected }].
+Overlaify.isTest                      true when random test events are running.
+```
+
+### Events
+
+Events have the same shape whatever platform they come from, so an overlay works on every platform
+Overlaify connects to without knowing which one it is on. Today that is Twitch; more will follow without a new
+spec version.
+
+Every event has `type`, `id`, `timestamp`, `platform` (`'twitch'`), `user` (login), `userId` (`''` when
+unknown), `name` (display name), `color` (hex or `null`) and `simulated` (boolean). Simulated events look like
+Twitch events.
+
+| Type | Extra fields |
+|---|---|
+| `chat` | `message`, `emotes`, `badges: string[]`, `isMod`, `isSub`, `isVip`, `isBroadcaster`, `bits`, `action` |
+| `follow` | — |
+| `sub` | `months`, `tier: 'prime' \| '1' \| '2' \| '3'`, `message` |
+| `gift` | `recipient`, `recipientName`, `tier`, `anonymous` |
+| `giftbomb` | `count`, `tier` (Twitch also sends one `gift` per recipient afterwards) |
+| `tip` | `amount`, `currency`, `kind`, `usd`, `display`, `message`, `emotes` |
+| `cheer` | `bits`, `message`, `emotes` (Twitch only) |
+| `raid` | `viewers` |
+
+`tip` is money from a viewer on any platform. `amount` is in `currency`, which is `'bits'` for Twitch bits or an
+ISO code such as `'USD'`; `kind` names the platform's feature (`'bits'` on Twitch); `usd` is the approximate
+value in US dollars, for thresholds and sizing; `display` is ready to show, such as `"500 bits"`. Twitch bits
+fire both `cheer` and `tip`. Handle `tip` in new overlays so they also count tips from other platforms, and
+never both, or bits count twice (`cheer_and_tip`, warning). `'*'` gets Twitch bits once, as the `cheer`.
+
+Lifecycle events, not included in `'*'`: `connected`, `disconnected`, with `platform` and `channel`; they fire
+for each source. Subscribing to any other name is reported as `unknown_event` (warning).
+
+### Where values come from
+
+- **Settings** saved by the streamer arrive as `window.OVERLAIFY_CONFIG`. URL query parameters override them.
+  Both are read with `Overlaify.param`.
+- Reserved keys, always provided by the platform: `channel`, `sources`, `volume`, `mute`, `test`.
+- **Sources** say where events come from: `OVERLAIFY_CONFIG.sources`, a list of `{ platform, channel }`,
+  plus `?channel=` as a Twitch source. One overlay can listen to several at once.
+- **Actions** come from the control page (`/c/:id`), the preview's keys, or `Overlaify.dispatch`.
+
+## 3. The manifest
+
+The overlay declares itself in a JSON block in `<head>`, before its own scripts:
+
+```html
+<script type="application/json" id="overlaify-manifest">
+{
+  "spec": 1,
+  "settings": [ ... ],
+  "actions": [ ... ]
+}
+</script>
+```
+
+| Rule | Code |
+|---|---|
+| Overlays that read settings or handle actions have a manifest. Without one, the streamer gets no settings panel or keys. | `manifest_missing` (warning) |
+| At most one manifest block. | `manifest_duplicate` |
+| `type="application/json"`, so the browser does not run it. | `manifest_type` |
+| Valid JSON object: double quotes, no comments, no trailing commas. | `manifest_json` |
+| `"spec": 1`. | `spec_missing` (warning), `spec_version` |
+| `settings` and `actions` are arrays when present. | `manifest_shape` |
+| No other top-level keys. | `manifest_unknown_key` (warning) |
+
+### Settings
+
+Settings are the overlay's starting state. The streamer edits them in a panel; the overlay reads each one with
+`Overlaify.param(key, fallback)`, using the manifest's default as the fallback.
+
+```json
+{ "key": "color", "label": "Fill color", "type": "color", "default": "#ff4f8b",
+  "swatches": ["#ff4f8b", "#ffb547", "#c6ff3d"], "group": "Look", "desc": "Bar and glow." }
+```
+
+| Field | Rule | Code |
+|---|---|---|
+| `key` | Required. Letters, digits, `_` or `-`, starting with a letter, at most 40 characters. Unique. | `setting_key`, `setting_duplicate` |
+| | Not a reserved key (`channel`, `volume`, `mute`, `test`). | `setting_reserved` |
+| `label` | Short name shown in the panel. | `setting_label` (warning) |
+| `type` | `text`, `number`, `toggle`, `color`, `select`, `segmented` or `range`. | `setting_type` |
+| `default` | Required, and matching the type (see below). | `setting_default_missing` (warning), `setting_default` |
+| `desc`, `group` | Optional strings. `group` puts settings under a heading; use groups once there are more than about 4 settings. | `setting_field` (warning) |
+
+By type:
+
+| Type | Default | Other fields |
+|---|---|---|
+| `text` | string | — |
+| `number` | number | — |
+| `toggle` | boolean; read with a boolean fallback | — |
+| `color` | `#rrggbb` | `swatches`: optional array of `#rrggbb` presets (`setting_swatches`) |
+| `select` | one of the option values | `options`: non-empty array (`setting_options`) |
+| `segmented` | one of the option values | `options`: 2–4 short choices (`setting_options`; more than 4 is a warning) |
+| `range` | number within `min`–`max` | `min` and `max` required, `min < max`, `step > 0`, optional `unit` (`setting_range`) |
+
+Options are plain values (`"subs"`) or `{ "value": "subs", "label": "Subs" }`.
+
+Consistency with the code:
+
+- Every setting is read with `Overlaify.param('key', …)`. → `setting_unused` (warning)
+- Every `Overlaify.param('key', …)`, other than reserved keys, is declared as a setting. → `param_undeclared` (warning)
+
+### Actions
+
+Actions change the overlay while it runs (pause, add time, reset, show a message). They appear as keys on the
+control page. Add them only when the overlay has state worth controlling live: timers, counters, goals, queues
+or toggled scenes.
+
+```json
+{ "name": "add", "label": "Add", "input": { "type": "number", "label": "Amount", "default": 1, "step": 1, "min": 1 } }
+```
+
+| Field | Rule | Code |
+|---|---|---|
+| `name` | Required, same format as setting keys, unique. | `action_name`, `action_duplicate` |
+| `label` | The key's text. | `action_label` (warning) |
+| `group` | Optional heading. | `action_field` (warning) |
+| `style` | `primary` (default), `secondary` (less used half of a pair) or `danger` (resets and clears). | `action_style` |
+| `confirm` | `true` or a short question. The key asks for a second press. Use it on anything that throws away progress. | `action_confirm` |
+| `wide` | `true` makes the key take a full row. | `action_field` (warning) |
+| `input` | `{ type: number \| text \| select, label, default, min?, max?, step?, options? }`: a value sent with the action. `select` needs `options`, and a `number` default must be a number. | `action_input` |
+
+Consistency with the code:
+
+- Every action has a handler, `Overlaify.action('name', fn)`. Otherwise its key does nothing. → `action_unhandled`
+- Every handler is declared in the manifest, unless it is only dispatched from the overlay's own code. → `action_undeclared` (warning)
+
+---
+
+## Versioning
+
+This is spec version 1. Additions that old overlays can ignore (new event types, new setting types, new
+optional fields) keep the version number. Changes that would break an existing overlay raise it and
+get a new SDK URL (`/sdk/v2/…`); `/sdk/v1/overlaify.js` stays as it is for v1 overlays.