overlaify 0.0.0-stage → 0.1.0

package/lib/publish.js

@@ -0,0 +1,255 @@
+// login / logout / whoami / publish / download: move overlays between this machine and My overlays on overlaify.com.
+// The CLI token lives in ~/.overlaify/credentials.json, one per site, so a local copy of the site
+// (--site http://localhost:8788) has its own. OVERLAIFY_TOKEN overrides it, for CI.
+import { createServer } from 'node:http';
+import { readFileSync, writeFileSync, mkdirSync, existsSync, chmodSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { homedir, hostname } from 'node:os';
+import { randomBytes } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { createInterface } from 'node:readline/promises';
+import { validateOverlay } from './validate.js';
+import { SDK_TAG } from './commands.js';
+
+export const DEFAULT_SITE = 'https://www.overlaify.com';
+const CREDENTIALS = join(homedir(), '.overlaify/credentials.json');
+const KINDS = ['alert', 'chat', 'goal', 'ticker', 'frame', 'custom'];
+
+export function siteUrl(site) {
+  const raw = site || process.env.OVERLAIFY_SITE || DEFAULT_SITE;
+  let url;
+  try { url = new URL(raw); } catch { throw new Error(`Not a URL: ${raw}`); }
+  return url.origin;
+}
+
+const readCredentials = () => {
+  try { return JSON.parse(readFileSync(CREDENTIALS, 'utf8')); } catch { return {}; }
+};
+
+function writeCredentials(all) {
+  mkdirSync(dirname(CREDENTIALS), { recursive: true });
+  writeFileSync(CREDENTIALS, JSON.stringify(all, null, 2) + '\n', { mode: 0o600 });
+  chmodSync(CREDENTIALS, 0o600);
+}
+
+const tokenFor = (site) => process.env.OVERLAIFY_TOKEN || readCredentials()[site]?.token || null;
+
+async function api(site, path, { method = 'GET', body, token = tokenFor(site) } = {}) {
+  const headers = { accept: 'application/json' };
+  if (token) headers.authorization = `Bearer ${token}`;
+  if (body) headers['content-type'] = 'application/json';
+  let res;
+  try {
+    res = await fetch(site + path, { method, headers, body: body && JSON.stringify(body) });
+  } catch (err) {
+    throw new Error(`Could not reach ${site} (${err.cause?.code || err.message}).`);
+  }
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) {
+    const e = new Error(data.error || `${method} ${path} failed (${res.status}).`);
+    e.status = res.status;
+    e.code = data.code;
+    throw e;
+  }
+  return data;
+}
+
+/** The signed-in user for a site, or null. */
+async function me(site, token) {
+  const { user } = await api(site, '/api/me', { token });
+  return user;
+}
+
+function openBrowser(url) {
+  const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'cmd' : 'xdg-open';
+  const args = process.platform === 'win32' ? ['/c', 'start', '', url] : [url];
+  try {
+    spawn(cmd, args, { stdio: 'ignore', detached: true }).on('error', () => {}).unref();
+  } catch {}
+}
+
+async function ask(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try { return (await rl.question(question)).trim(); } finally { rl.close(); }
+}
+
+/**
+ * overlaify login [--site url] [--token t] [--no-browser]
+ * Opens <site>/cli, where the signed-in user allows the CLI; the page hands the token back to a one-off
+ * server on 127.0.0.1. With --no-browser (or over SSH) the page shows the token to paste instead.
+ */
+export async function login({ site, token, browser = true, log = console.log } = {}) {
+  site = siteUrl(site);
+  if (!token) token = browser ? await tokenFromBrowser(site, log) : await tokenFromPaste(site, log);
+  token = token.trim();
+  const user = await me(site, token).catch(() => null);
+  if (!user) throw new Error('That token was not accepted. Run overlaify login again.');
+  const all = readCredentials();
+  all[site] = { token, user: { id: user.id, name: user.name } };
+  writeCredentials(all);
+  return { site, user };
+}
+
+function tokenFromBrowser(site, log) {
+  const state = randomBytes(16).toString('hex');
+  return new Promise((resolveToken, reject) => {
+    const server = createServer((req, res) => {
+      const url = new URL(req.url, 'http://127.0.0.1');
+      if (url.pathname !== '/callback') { res.writeHead(404).end(); return; }
+      const token = url.searchParams.get('token');
+      if (url.searchParams.get('state') !== state || !/^ovl_[0-9a-f]{64}$/.test(token || '')) {
+        res.writeHead(400, { 'content-type': 'text/plain' }).end('This sign-in link does not match. Run overlaify login again.');
+        return;
+      }
+      res.writeHead(302, { location: `${site}/my` }).end();
+      clearTimeout(timer);
+      server.close();
+      resolveToken(token);
+    });
+    const timer = setTimeout(() => { server.close(); reject(new Error('Timed out waiting for the browser. Run overlaify login again, or use --no-browser.')); }, 5 * 60 * 1000);
+    server.on('error', reject);
+    server.listen(0, '127.0.0.1', () => {
+      const q = new URLSearchParams({ port: String(server.address().port), state, name: hostname() });
+      const url = `${site}/cli?${q}`;
+      log(`Opening ${url}\nAllow the CLI there (sign in first if asked). Waiting…`);
+      openBrowser(url);
+    });
+  });
+}
+
+async function tokenFromPaste(site, log) {
+  if (!process.stdin.isTTY) throw new Error('Pass the token with --token, or set OVERLAIFY_TOKEN.');
+  log(`Open ${site}/cli in a browser, allow the CLI and copy the token it shows.`);
+  return ask('Token: ');
+}
+
+/** overlaify logout [--site url] — revokes the token on the site and forgets it here. */
+export async function logout({ site } = {}) {
+  site = siteUrl(site);
+  const all = readCredentials();
+  if (!all[site]) return false;
+  await api(site, '/api/cli/token', { method: 'DELETE', token: all[site].token }).catch(() => {});
+  delete all[site];
+  writeCredentials(all);
+  return true;
+}
+
+/** overlaify whoami [--site url] → the user, or null when not logged in. */
+export async function whoami({ site } = {}) {
+  site = siteUrl(site);
+  if (!tokenFor(site)) return null;
+  return me(site);
+}
+
+// Where a file was published: .overlaify/<name>.publish.json → { [site]: { projectId, id, url } },
+// next to the settings `overlaify dev` keeps in .overlaify/<name>.json.
+const stateFile = (file, ext) => join(dirname(file), '.overlaify', basename(file).replace(/\.html?$/i, '') + ext);
+const readJsonFile = (f) => {
+  try { return JSON.parse(readFileSync(f, 'utf8')); } catch { return null; }
+};
+
+const titleOf = (html, file) =>
+  (/<title[^>]*>([^<]*)<\/title>/i.exec(html)?.[1] || '').replace(/\s+/g, ' ').trim() || basename(file).replace(/\.html?$/i, '');
+
+/**
+ * overlaify publish [file] [--public | --private] [--name n] [--title t] [--kind k] [--new] [--site url]
+ * Uploads the overlay to My overlays. The first publish of a file asks public or private; publishing it
+ * again adds a new version to the same overlay (its OBS URL changes to the new version's) unless --new.
+ * `name` is its address, overlaify.com/<handle>/<name>; a new overlay is otherwise named after its title.
+ */
+export async function publish(file, { site, visibility, name, title, kind, fresh, log = console.log } = {}) {
+  site = siteUrl(site);
+  file = resolve(file);
+  if (!existsSync(file)) throw new Error(`No such file: ${file}`);
+  if (kind && !KINDS.includes(kind)) throw new Error(`--kind must be one of ${KINDS.join(', ')}.`);
+  if (name != null && !/^[a-z0-9](?:[a-z0-9-]{0,58}[a-z0-9])?$/.test(name)) {
+    throw new Error('--name must be 1–60 lowercase letters, digits or dashes, not at the start or end.');
+  }
+  if (!tokenFor(site)) throw new Error(`Not logged in to ${site}. Run: overlaify login${site === DEFAULT_SITE ? '' : ` --site ${site}`}`);
+
+  const html = readFileSync(file, 'utf8');
+  const check = validateOverlay(html);
+  if (!check.ok) {
+    throw new Error(`${basename(file)} doesn't pass the spec. Fix these first (overlaify validate ${basename(file)}):\n` +
+      check.errors.map((i) => `  [${i.code}] ${i.message}`).join('\n'));
+  }
+
+  const published = readJsonFile(stateFile(file, '.publish.json')) || {};
+  const previous = fresh ? null : published[site];
+  if (!visibility && !previous) {
+    if (!process.stdin.isTTY) throw new Error('Choose who can see it: --public or --private.');
+    log('Who can open this overlay on Overlaify?\n  1) Private — only you (its OBS URL still works)\n  2) Public  — anyone with a link');
+    const a = (await ask('Choose 1 or 2 [1]: ')).toLowerCase();
+    visibility = a === '2' || a.startsWith('pub') ? 'public' : a === '' || a === '1' || a.startsWith('pri') ? 'private' : null;
+    if (!visibility) throw new Error('Publishing cancelled.');
+  }
+
+  const body = { html, title: title || titleOf(html, file), name, kind, visibility, config: readJsonFile(stateFile(file, '.json')) || undefined };
+  let out;
+  try {
+    out = await api(site, '/api/my/overlays/publish', { method: 'POST', body: { ...body, projectId: previous?.projectId } });
+  } catch (err) {
+    // The overlay was deleted on the site: publish it as a new one, which needs a visibility.
+    if (err.code !== 'project_not_found' || !previous) throw err;
+    log(`The overlay published from ${basename(file)} is no longer in your account; publishing it as a new one.`);
+    out = await api(site, '/api/my/overlays/publish', { method: 'POST', body: { ...body, visibility: visibility || 'private' } });
+  }
+
+  published[site] = { projectId: out.projectId, id: out.id, url: out.url };
+  mkdirSync(dirname(stateFile(file, '.publish.json')), { recursive: true });
+  writeFileSync(stateFile(file, '.publish.json'), JSON.stringify(published, null, 2) + '\n');
+  return out;
+}
+
+// An overlay on the site: handle/name, @handle/name, or its page URL (whose origin is then the site).
+function parseRef(ref, site) {
+  let path = String(ref || '');
+  if (/^https?:\/\//i.test(path)) {
+    const url = new URL(path);
+    site ||= url.origin;
+    path = url.pathname;
+  }
+  const m = /^\/?@?([a-z0-9_-]+)\/([a-z0-9-]+)\/?$/i.exec(path);
+  if (!m) throw new Error('Name an overlay as <user>/<name>, e.g. overlaify download alice/neon-alert (or paste its page URL).');
+  return { site: siteUrl(site), handle: m[1].toLowerCase(), name: m[2].toLowerCase() };
+}
+
+/**
+ * overlaify download <user>/<name> [file] [--version n] [--force] [--site url]
+ * Saves an overlay from overlaify.com/<user>/<name> as a local file (default <name>.html), with the SDK tag
+ * put back so it runs on its own. A private overlay needs its owner to be logged in. For your own overlay the
+ * saved settings come along for `overlaify dev`, and `overlaify publish` then adds versions to that overlay.
+ */
+export async function download(ref, file, { site, version, force } = {}) {
+  const { site: origin, handle, name } = parseRef(ref, site);
+  site = origin;
+  if (version != null && !/^[1-9]\d*$/.test(String(version))) throw new Error('--version must be a version number: 1 is the first.');
+  let out;
+  try {
+    out = await api(site, `/api/u/${handle}/${name}${version != null ? `?version=${version}` : ''}`);
+  } catch (err) {
+    if (err.status === 401) {
+      const how = `overlaify login${site === DEFAULT_SITE ? '' : ` --site ${site}`}`;
+      throw new Error(`${handle}/${name} is private. ${tokenFor(site) ? 'Your login has expired; log in again' : 'If it is yours, log in first'}: ${how}`);
+    }
+    throw err;
+  }
+  if (typeof out.html !== 'string') throw new Error(`${site} doesn't support downloads yet (no /api/u/${handle}/${name}).`);
+
+  file = resolve(file || `${name}.html`);
+  if (existsSync(file) && !force) throw new Error(`${basename(file)} already exists (use --force to overwrite).`);
+  const html = /<head[^>]*>/i.test(out.html)
+    ? out.html.replace(/<head[^>]*>/i, (m) => `${m}\n${SDK_TAG}`)
+    : `${SDK_TAG}\n${out.html}`;
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, html);
+
+  if (out.owned) {
+    mkdirSync(dirname(stateFile(file, '.json')), { recursive: true });
+    if (out.config && Object.keys(out.config).length) writeFileSync(stateFile(file, '.json'), JSON.stringify(out.config, null, 2) + '\n');
+    const published = readJsonFile(stateFile(file, '.publish.json')) || {};
+    published[site] = { projectId: out.projectId, id: out.id, url: `${site}/o/${out.id}` };
+    writeFileSync(stateFile(file, '.publish.json'), JSON.stringify(published, null, 2) + '\n');
+  }
+  return { ...out, file, page: `${site}/${handle}/${name}` };
+}

package/lib/starter.html

@@ -0,0 +1,51 @@
+<!doctype html>
+<html>
+<head>
+<meta charset="utf-8">
+<title>My overlay</title>
+<script src="https://www.overlaify.com/sdk/v1/overlaify.js"></script>
+<!-- Follows Overlay Spec v1; check it with: npx overlaify validate <file> -->
+<script type="application/json" id="overlaify-manifest">
+{
+  "spec": 1,
+  "settings": [
+    { "key": "color", "label": "Accent color", "type": "color", "default": "#c6ff3d", "swatches": ["#c6ff3d", "#ff4f8b", "#5ce1ff", "#ffb547", "#b48bff"] },
+    { "key": "duration", "label": "On screen", "type": "range", "min": 2, "max": 15, "step": 0.5, "unit": "s", "default": 5 }
+  ],
+  "actions": [
+    { "name": "test", "label": "Show a test alert" }
+  ]
+}
+</script>
+<style>
+  html, body { margin: 0; width: 1920px; height: 1080px; overflow: hidden; background: transparent; }
+  #card { position: absolute; left: 50%; top: 120px; transform: translate(-50%, -30px); opacity: 0; transition: transform .45s, opacity .45s;
+    padding: 28px 48px; border-radius: 20px; background: rgba(11, 10, 16, .85); border: 3px solid var(--c); box-shadow: 0 0 40px var(--c);
+    color: #fff; font: 800 54px/1.1 system-ui, sans-serif; text-align: center; text-shadow: 0 3px 10px rgba(0, 0, 0, .6); }
+  #card.on { opacity: 1; transform: translate(-50%, 0); }
+  #card small { display: block; font-size: 24px; font-weight: 600; letter-spacing: .08em; text-transform: uppercase; color: var(--c); }
+</style>
+</head>
+<body>
+<div id="card"><small id="kicker"></small><span id="name"></span></div>
+<script>
+  const card = document.getElementById('card');
+  document.documentElement.style.setProperty('--c', Overlaify.param('color', '#c6ff3d'));
+  const DURATION = Overlaify.param('duration', 5) * 1000;
+
+  const WORDS = { follow: 'New follower', sub: 'New subscriber', gift: 'Gifted a sub', giftbomb: 'Gift bomb', tip: 'Tipped', raid: 'Raid' };
+  const show = Overlaify.queue(async (e) => {
+    document.getElementById('kicker').textContent = WORDS[e.type] || e.type;
+    document.getElementById('name').textContent = e.type === 'tip' ? `${e.name} · ${e.display}` : e.name;
+    card.classList.add('on');
+    Overlaify.chime('alert');
+    await Overlaify.sleep(DURATION);
+    card.classList.remove('on');
+    await Overlaify.sleep(500);
+  });
+
+  Object.keys(WORDS).forEach((type) => Overlaify.on(type, show));
+  Overlaify.action('test', () => Overlaify.simulate('sub'));
+</script>
+</body>
+</html>

package/lib/validate.js

@@ -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.`);
+}