npm - overlaify - Versions diffs - 0.0.0-stage → 0.1.2 - Mend

overlaify 0.0.0-stage → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (30) hide show

package/LICENSE +21 -0
package/README.md +123 -2
package/assets/overlay-spec.md +196 -0
package/assets/sdk/v1/overlaify.js +437 -0
package/assets/templates/be-right-back.html +123 -0
package/assets/templates/catalog.json +348 -0
package/assets/templates/chat-stack.html +68 -0
package/assets/templates/death-counter.html +94 -0
package/assets/templates/emote-wall.html +125 -0
package/assets/templates/goal-bar.html +89 -0
package/assets/templates/hug-command.html +151 -0
package/assets/templates/neon-alert.html +84 -0
package/assets/templates/newsroom-ticker.html +136 -0
package/assets/templates/starting-soon.html +145 -0
package/assets/templates/subathon-timer.html +127 -0
package/assets/templates/webcam-frame.html +93 -0
package/bin/overlaify.js +114 -0
package/lib/commands.js +67 -0
package/lib/dev.html +328 -0
package/lib/dev.js +181 -0
package/lib/publish.js +272 -0
package/lib/starter.html +51 -0
package/lib/validate.js +362 -0
package/lib/ws.js +79 -0
package/package.json +35 -4
package/skill/SKILL.md +88 -0
package/skill/examples/chat-stack.html +68 -0
package/skill/examples/goal-bar.html +89 -0
package/skill/examples/neon-alert.html +84 -0
package/skill/references/overlay-spec.md +196 -0

package/lib/validate.js ADDED Viewed

@@ -0,0 +1,362 @@
+// Checks an overlay's HTML against the Overlaify Overlay Spec (docs/overlay-spec.md).
+// Plain string scanning, no DOM, so it runs the same in Pages Functions, Node scripts and a future CLI.
+export const SPEC_VERSION = 1;
+export const MAX_BYTES = 80000;
+export const SETTING_TYPES = ['text', 'number', 'toggle', 'color', 'select', 'segmented', 'range'];
+export const ACTION_STYLES = ['primary', 'secondary', 'danger'];
+export const INPUT_TYPES = ['number', 'text', 'select'];
+export const RESERVED_KEYS = ['channel', 'sources', 'volume', 'mute', 'test'];
+export const EVENTS = ['chat', 'follow', 'sub', 'gift', 'giftbomb', 'cheer', 'tip', 'raid'];
+const LIFECYCLE = ['connected', 'disconnected', '*'];
+const ALLOWED_HOSTS = ['fonts.googleapis.com', 'fonts.gstatic.com', 'static-cdn.jtvnw.net'];
+const SDK_HOSTS = ['www.overlaify.com', 'overlaify.com'];
+// Namespaces, not requests.
+const NAMESPACE_HOSTS = ['www.w3.org'];
+const NAME = /^[A-Za-z][A-Za-z0-9_-]{0,39}$/;
+const HEX = /^#[0-9a-f]{6}$/i;
+/**
+ * validateOverlay(html) → { ok, errors, warnings, manifest }
+ * Each issue is { code, message }. `ok` means no errors; warnings don't block hosting.
+ */
+export function validateOverlay(html) {
+  const errors = [];
+  const warnings = [];
+  const err = (code, message) => errors.push({ code, message });
+  const warn = (code, message) => warnings.push({ code, message });
+  html = String(html || '');
+  checkDocument(html, err, warn);
+  const blocks = manifestBlocks(html);
+  let manifest = null;
+  if (blocks.length > 1) err('manifest_duplicate', `Found ${blocks.length} overlaify-manifest blocks; keep one.`);
+  if (blocks.length) {
+    const b = blocks[0];
+    if (!/\btype\s*=\s*["']?application\/json\b/i.test(b.attrs)) {
+      err('manifest_type', 'The overlaify-manifest <script> needs type="application/json".');
+    }
+    try {
+      manifest = JSON.parse(b.body);
+    } catch (e) {
+      err('manifest_json', `The manifest is not valid JSON (${e.message}). Use double quotes, no comments, no trailing commas.`);
+    }
+    if (manifest !== null && (typeof manifest !== 'object' || Array.isArray(manifest))) {
+      err('manifest_json', 'The manifest must be a JSON object: { "spec": 1, "settings": [...], "actions": [...] }.');
+      manifest = null;
+    }
+    if (manifest) checkManifest(manifest, err, warn);
+  }
+  checkCode(stripManifest(html), manifest, blocks.length > 0, err, warn);
+  return { ok: errors.length === 0, errors, warnings, manifest };
+}
+/** The issues as a bulleted list, for showing a person or asking a model to fix them. */
+export function formatIssues(issues) {
+  return issues.map((i) => `- [${i.code}] ${i.message}`).join('\n');
+}
+/* ------------------------------------------------------------------ */
+/* Document                                                            */
+/* ------------------------------------------------------------------ */
+function checkDocument(html, err, warn) {
+  const bytes = new TextEncoder().encode(html).length;
+  if (bytes > MAX_BYTES) err('too_large', `The overlay is ${Math.round(bytes / 1000)} KB; the limit is ${MAX_BYTES / 1000} KB.`);
+  if (!/<html[\s>]/i.test(html)) warn('not_html', 'Not a complete HTML document; wrap it in <!doctype html><html>…</html>.');
+  if (!/<title>\s*[^<\s][^<]*<\/title>/i.test(html)) warn('title_missing', 'Add a short overlay name in <title>.');
+  const tags = html.match(/<[a-z][^>]*>/gi) || [];
+  for (const tag of tags) {
+    const name = tag.match(/^<([a-z0-9-]+)/i)[1].toLowerCase();
+    if (name === 'iframe' || name === 'object' || name === 'embed') {
+      err('embedded_frame', `<${name}> is not allowed; overlays can't embed other pages.`);
+      continue;
+    }
+    if (name === 'script') {
+      const src = attr(tag, 'src');
+      // The SDK tag is fine (local previews need it); Overlaify swaps it for its own when hosting.
+      if (src !== null && !isSdkUrl(src)) {
+        err('external_script', `<script src="${short(src)}"> is not allowed; put all JS inline.`);
+      }
+      continue;
+    }
+    if (name === 'link') {
+      const href = attr(tag, 'href');
+      const rel = (attr(tag, 'rel') || '').toLowerCase();
+      // preconnect/dns-prefetch only warm up a connection; they load nothing.
+      if (href !== null && !isDynamic(href) && !/\b(preconnect|dns-prefetch)\b/.test(rel) && !allowedUrl(href)) {
+        err('external_resource', `<link href="${short(href)}"> loads an external file; inline it (only Google Fonts are allowed).`);
+      }
+      continue;
+    }
+    for (const a of ['src', 'poster', 'data']) {
+      const v = attr(tag, a);
+      if (v !== null && !isDynamic(v) && !allowedUrl(v)) {
+        err('external_resource', `<${name} ${a}="${short(v)}"> loads an external file; use a data: URL, inline SVG, canvas or emoji.`);
+      }
+    }
+    if (name === 'image' || name === 'use' || name === 'feimage') {
+      const v = attr(tag, 'href') ?? attr(tag, 'xlink:href');
+      if (v !== null && !v.startsWith('#') && !isDynamic(v) && !allowedUrl(v)) {
+        err('external_resource', `<${name} href="${short(v)}"> loads an external file.`);
+      }
+    }
+  }
+  // CSS only: <style> blocks and style="" attributes (in JS, url(...) is usually a function call).
+  const css = [...html.matchAll(/<style\b[^>]*>([\s\S]*?)<\/style\s*>/gi)].map((m) => m[1])
+    .concat(tags.map((t) => attr(t, 'style')).filter(Boolean)).join('\n');
+  for (const m of css.matchAll(/url\(\s*(['"]?)([^'")]*)\1\s*\)/gi)) {
+    const u = m[2].trim();
+    if (u && !u.startsWith('#') && !isDynamic(u) && !allowedUrl(u)) err('external_resource', `CSS url(${short(u)}) loads an external file; use a data: URL or a gradient.`);
+  }
+  // @import url(...) was covered above.
+  for (const m of css.matchAll(/@import\s+['"]([^'"]+)/gi)) {
+    if (!allowedUrl(m[1])) err('external_resource', `@import ${short(m[1])} loads an external stylesheet; inline it (only Google Fonts are allowed).`);
+  }
+}
+// data:/blob: and the spec's allowed hosts. Relative URLs have nothing to load from on Overlaify.
+function allowedUrl(u) {
+  u = u.trim();
+  if (!u || /^(data|blob):/i.test(u)) return true;
+  const host = hostOf(u);
+  return host !== null && ALLOWED_HOSTS.includes(host);
+}
+// Markup built in JS (`<img src="${url}">`, 'url(' + x + ')') is filled in at run time; the scan can't judge it.
+function isDynamic(v) {
+  return /\$\{|['"`]|\s\+|\+\s/.test(v);
+}
+// /sdk/v1/overlaify.js, on Overlaify or relative to wherever the overlay is served (overlaify dev).
+function isSdkUrl(u) {
+  const host = hostOf(u);
+  return (host === null || SDK_HOSTS.includes(host)) && /(^|\/)sdk\/(v\d+\/)?overlaify(\.min)?\.js(\?|$)/i.test(u);
+}
+function hostOf(u) {
+  const m = u.match(/^(?:https?:)?\/\/([^/?#:\s]+)/i);
+  return m ? m[1].toLowerCase() : null;
+}
+function attr(tag, name) {
+  const re = new RegExp(`\\s${name.replace(':', '\\:')}\\s*=\\s*(?:"([^"]*)"|'([^']*)'|([^\\s>]+))`, 'i');
+  const m = tag.match(re);
+  return m ? (m[1] ?? m[2] ?? m[3]) : null;
+}
+function short(s) {
+  return s.length > 60 ? s.slice(0, 57) + '...' : s;
+}
+/* ------------------------------------------------------------------ */
+/* Manifest                                                            */
+/* ------------------------------------------------------------------ */
+const SCRIPT = /<script\b([^>]*)>([\s\S]*?)<\/script\s*>/gi;
+const isManifest = (attrs) => /\bid\s*=\s*["']?overlaify-manifest\b/i.test(attrs);
+function manifestBlocks(html) {
+  return [...html.matchAll(SCRIPT)].filter((m) => isManifest(m[1])).map((m) => ({ attrs: m[1], body: m[2] }));
+}
+function stripManifest(html) {
+  return html.replace(SCRIPT, (all, attrs) => (isManifest(attrs) ? '' : all));
+}
+function checkManifest(m, err, warn) {
+  if (!('spec' in m)) warn('spec_missing', `Add "spec": ${SPEC_VERSION} to the manifest.`);
+  else if (m.spec !== SPEC_VERSION) err('spec_version', `Unknown spec version ${JSON.stringify(m.spec)}; this validator knows spec ${SPEC_VERSION}.`);
+  for (const k of Object.keys(m)) {
+    if (!['spec', 'settings', 'actions'].includes(k)) warn('manifest_unknown_key', `Unknown manifest key "${k}"; only spec, settings and actions are read.`);
+  }
+  if ('settings' in m && !Array.isArray(m.settings)) err('manifest_shape', '"settings" must be an array.');
+  if ('actions' in m && !Array.isArray(m.actions)) err('manifest_shape', '"actions" must be an array.');
+  const keys = new Set();
+  (Array.isArray(m.settings) ? m.settings : []).forEach((s, i) => checkSetting(s, i, keys, err, warn));
+  const names = new Set();
+  (Array.isArray(m.actions) ? m.actions : []).forEach((a, i) => checkAction(a, i, names, err, warn));
+}
+function checkSetting(s, i, keys, err, warn) {
+  if (!s || typeof s !== 'object' || Array.isArray(s)) return err('setting_key', `settings[${i}] must be an object.`);
+  const at = typeof s.key === 'string' ? `Setting "${s.key}"` : `settings[${i}]`;
+  if (typeof s.key !== 'string' || !NAME.test(s.key)) {
+    err('setting_key', `${at}: "key" must be letters, digits, _ or -, starting with a letter (max 40).`);
+  } else if (RESERVED_KEYS.includes(s.key)) {
+    err('setting_reserved', `${at}: "${s.key}" is reserved; the platform always provides ${RESERVED_KEYS.join(', ')}.`);
+  } else if (keys.has(s.key)) {
+    err('setting_duplicate', `${at} is declared twice.`);
+  } else {
+    keys.add(s.key);
+  }
+  if (typeof s.label !== 'string' || !s.label.trim()) warn('setting_label', `${at}: add a short "label".`);
+  for (const f of ['desc', 'group']) {
+    if (f in s && typeof s[f] !== 'string') warn('setting_field', `${at}: "${f}" should be a string.`);
+  }
+  if (!SETTING_TYPES.includes(s.type)) {
+    return err('setting_type', `${at}: "type" must be one of ${SETTING_TYPES.join(', ')}.`);
+  }
+  const has = 'default' in s;
+  const d = s.default;
+  if (!has) warn('setting_default_missing', `${at}: add a "default" (the value the overlay starts with).`);
+  const bad = (want) => err('setting_default', `${at}: "default" must be ${want}, got ${JSON.stringify(d)}.`);
+  switch (s.type) {
+    case 'text':
+      if (has && typeof d !== 'string') bad('a string');
+      break;
+    case 'number':
+      if (has && !isNum(d)) bad('a number');
+      break;
+    case 'toggle':
+      if (has && typeof d !== 'boolean') bad('true or false');
+      break;
+    case 'color':
+      if (has && !(typeof d === 'string' && HEX.test(d))) bad('a #rrggbb color');
+      if ('swatches' in s && !(Array.isArray(s.swatches) && s.swatches.every((c) => typeof c === 'string' && HEX.test(c)))) {
+        err('setting_swatches', `${at}: "swatches" must be an array of #rrggbb colors.`);
+      }
+      break;
+    case 'select':
+    case 'segmented': {
+      const values = optionValues(s.options);
+      if (!values) {
+        err('setting_options', `${at}: "options" must be a non-empty array of values or { "value", "label" }.`);
+        break;
+      }
+      if (s.type === 'segmented' && values.length > 4) warn('setting_options', `${at}: segmented fits 2-4 choices; use "select" for ${values.length}.`);
+      if (has && !values.includes(String(d))) bad(`one of the options (${values.join(', ')})`);
+      break;
+    }
+    case 'range':
+      if (!isNum(s.min) || !isNum(s.max) || s.min >= s.max) {
+        err('setting_range', `${at}: a range needs numeric "min" < "max".`);
+      } else if (has && (!isNum(d) || d < s.min || d > s.max)) {
+        bad(`a number from ${s.min} to ${s.max}`);
+      }
+      if ('step' in s && !(isNum(s.step) && s.step > 0)) err('setting_range', `${at}: "step" must be a number above 0.`);
+      break;
+  }
+}
+function checkAction(a, i, names, err, warn) {
+  if (!a || typeof a !== 'object' || Array.isArray(a)) return err('action_name', `actions[${i}] must be an object.`);
+  const at = typeof a.name === 'string' ? `Action "${a.name}"` : `actions[${i}]`;
+  if (typeof a.name !== 'string' || !NAME.test(a.name)) {
+    err('action_name', `${at}: "name" must be letters, digits, _ or -, starting with a letter (max 40).`);
+  } else if (names.has(a.name)) {
+    err('action_duplicate', `${at} is declared twice.`);
+  } else {
+    names.add(a.name);
+  }
+  if (typeof a.label !== 'string' || !a.label.trim()) warn('action_label', `${at}: add a "label" for its key.`);
+  if ('group' in a && typeof a.group !== 'string') warn('action_field', `${at}: "group" should be a string.`);
+  if ('wide' in a && typeof a.wide !== 'boolean') warn('action_field', `${at}: "wide" should be true or false.`);
+  if ('style' in a && !ACTION_STYLES.includes(a.style)) err('action_style', `${at}: "style" must be one of ${ACTION_STYLES.join(', ')}.`);
+  if ('confirm' in a && typeof a.confirm !== 'boolean' && typeof a.confirm !== 'string') {
+    err('action_confirm', `${at}: "confirm" must be true or a short question.`);
+  }
+  if (!('input' in a)) return;
+  const p = a.input;
+  if (!p || typeof p !== 'object' || !INPUT_TYPES.includes(p.type)) {
+    return err('action_input', `${at}: "input" must be { "type": ${INPUT_TYPES.join(' | ')}, "label", "default", ... }.`);
+  }
+  if (p.type === 'number') {
+    for (const f of ['default', 'min', 'max', 'step']) {
+      if (f in p && !isNum(p[f])) err('action_input', `${at}: input "${f}" must be a number.`);
+    }
+  }
+  if (p.type === 'select') {
+    const values = optionValues(p.options);
+    if (!values) err('action_input', `${at}: a select input needs non-empty "options".`);
+    else if ('default' in p && !values.includes(String(p.default))) err('action_input', `${at}: input "default" must be one of the options.`);
+  }
+}
+function optionValues(options) {
+  if (!Array.isArray(options) || !options.length) return null;
+  const out = [];
+  for (const o of options) {
+    if (typeof o === 'string' || isNum(o)) out.push(String(o));
+    else if (o && typeof o === 'object' && (typeof o.value === 'string' || isNum(o.value))) out.push(String(o.value));
+    else return null;
+  }
+  return out;
+}
+const isNum = (n) => typeof n === 'number' && Number.isFinite(n);
+/* ------------------------------------------------------------------ */
+/* Code                                                                */
+/* ------------------------------------------------------------------ */
+// Literal first arguments of Overlaify.<fn>('...'), e.g. calls('param') → Set of setting keys read.
+function calls(code, fn) {
+  const re = new RegExp(`\\bOverlaify\\s*\\.\\s*${fn}\\s*\\(\\s*(['"\`])([^'"\`]+)\\1`, 'g');
+  return new Set([...code.matchAll(re)].map((m) => m[2]));
+}
+function checkCode(code, manifest, hasManifest, err, warn) {
+  const params = calls(code, 'param');
+  const handlers = calls(code, 'action');
+  const settings = new Set((Array.isArray(manifest?.settings) ? manifest.settings : []).map((s) => s?.key)
+    .filter((k) => typeof k === 'string' && NAME.test(k) && !RESERVED_KEYS.includes(k)));
+  const actions = new Set((Array.isArray(manifest?.actions) ? manifest.actions : []).map((a) => a?.name).filter(Boolean));
+  const ownParams = [...params].filter((k) => !RESERVED_KEYS.includes(k));
+  if (!hasManifest && (ownParams.length || handlers.size)) {
+    warn('manifest_missing', 'The overlay reads settings or handles actions but has no overlaify-manifest, so the streamer gets no settings panel or keys.');
+  }
+  if (manifest) {
+    // Overlaify.params.get(...) or a computed key reads settings this scan can't see.
+    const dynamic = /\bOverlaify\s*\.\s*params\b/.test(code) || /\bOverlaify\s*\.\s*param\s*\(\s*[^'"`\s)]/.test(code);
+    if (!dynamic) {
+      for (const k of settings) {
+        if (!params.has(k)) warn('setting_unused', `Setting "${k}" is never read; use Overlaify.param('${k}', <default>) or remove it.`);
+      }
+    }
+    for (const k of ownParams) {
+      if (!settings.has(k)) warn('param_undeclared', `Overlaify.param('${k}') is not declared in the manifest's settings, so the panel can't set it.`);
+    }
+    const dynamicActions = /\bOverlaify\s*\.\s*action\s*\(\s*[^'"`\s)]/.test(code);
+    if (!dynamicActions) {
+      for (const n of actions) {
+        if (!handlers.has(n)) err('action_unhandled', `Action "${n}" has no handler; add Overlaify.action('${n}', fn) or remove it, or its key does nothing.`);
+      }
+    }
+    for (const n of handlers) {
+      if (!actions.has(n)) warn('action_undeclared', `Overlaify.action('${n}') is not in the manifest, so the streamer has no key for it.`);
+    }
+  }
+  const events = calls(code, 'on');
+  for (const t of events) {
+    if (!EVENTS.includes(t) && !LIFECYCLE.includes(t) && !t.startsWith('action:')) {
+      warn('unknown_event', `Overlaify.on('${t}') never fires; events are ${EVENTS.join(', ')} (plus connected, disconnected, '*').`);
+    }
+  }
+  if (events.has('cheer') && events.has('tip')) {
+    warn('cheer_and_tip', `Twitch bits fire both 'cheer' and 'tip', so handling both counts them twice; handle 'tip' alone.`);
+  }
+  const scripts = [...code.matchAll(SCRIPT)].map((m) => m[2]).join('\n');
+  const net = scripts.match(/\b(fetch|XMLHttpRequest|WebSocket|EventSource)\s*\(/);
+  if (net) warn('network_access', `${net[1]}() makes network calls; overlays get events from the SDK.`);
+  const dialog = scripts.match(/(?:^|[^\w$.]|\bwindow\.)(alert|confirm|prompt)\s*\(/);
+  if (dialog) warn('blocking_dialog', `${dialog[1]}() needs a person to click; overlays must just run.`);
+  const urls = new Set();
+  for (const m of code.matchAll(/\bhttps?:\/\/[^\s"'`)<>]+/gi)) {
+    const host = hostOf(m[0]);
+    if (host && !ALLOWED_HOSTS.includes(host) && !NAMESPACE_HOSTS.includes(host) && !SDK_HOSTS.includes(host)) urls.add(host);
+  }
+  if (urls.size) warn('external_url', `The code mentions ${[...urls].join(', ')}; overlays can only load from Google Fonts and Twitch emotes.`);
+}

package/lib/ws.js ADDED Viewed

@@ -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 CHANGED Viewed

@@ -1,6 +1,37 @@
 {
   "name": "overlaify",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.2",
+  "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 ADDED Viewed

@@ -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 (named after the file, e.g. `my-alert.html` → `my-alert`; `--name` sets another). 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 ADDED Viewed

@@ -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>