@nebularstreams/overlay-sdk 1.0.0

package/skill/nebular-overlay/scripts/validate-templates.mjs

@@ -0,0 +1,244 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+
+const SUPPORTED_TYPES = new Set(["string", "number", "range", "date", "color", "choose", "select", "multi", "set", "selector", "action", "reset"]);
+const SUPPORTED_ASSETS = new Set([".css", ".jpg", ".jpeg", ".png", ".webp", ".otf", ".ttf", ".woff", ".woff2"]);
+const PATH_SEGMENT = /^[A-Za-z0-9_-]+$/;
+const MAX_ASSET_SIZE = 5 * 1024 * 1024;
+const errors = [];
+const warnings = [];
+
+function report(collection, file, message) {
+  collection.push(`${file}: ${message}`);
+}
+
+function isObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function walk(directory) {
+  return fs.readdirSync(directory, {withFileTypes: true}).flatMap(entry => {
+    if (entry.name.startsWith(".") || entry.name === "node_modules") return [];
+    const item = path.join(directory, entry.name);
+    return entry.isDirectory() ? walk(item) : [item];
+  });
+}
+
+function choiceValue(choice) {
+  return isObject(choice) && Object.hasOwn(choice, "value") ? choice.value : choice;
+}
+
+function matchesChoice(value, choice) {
+  const expected = choiceValue(choice);
+  return value === expected || ((typeof value === "string" || typeof value === "number")
+    && (typeof expected === "string" || typeof expected === "number")
+    && String(value) === String(expected));
+}
+
+function validateValue(value, definition, location) {
+  if (value === null) {
+    if (definition.remove === true || definition.default === null) return;
+    report(errors, location, "null is not supported by this definition");
+    return;
+  }
+
+  switch (definition.type) {
+    case "string":
+      if (typeof value !== "string") report(errors, location, "default must be a string");
+      if (typeof value === "string" && Number.isInteger(definition.maxLength) && value.length > definition.maxLength) report(errors, location, `default exceeds maxLength ${definition.maxLength}`);
+      break;
+    case "number":
+    case "range": {
+      const number = Number(value);
+      if ((typeof value !== "number" && typeof value !== "string") || value === "" || !Number.isFinite(number)) {
+        report(errors, location, "default must be a finite number");
+      } else {
+        if (definition.min != null && number < Number(definition.min)) report(errors, location, "default is below min");
+        if (definition.max != null && number > Number(definition.max)) report(errors, location, "default is above max");
+      }
+      break;
+    }
+    case "date":
+      if (typeof value !== "number" || !Number.isFinite(value)) report(errors, location, "default must be an epoch-millisecond number");
+      break;
+    case "color":
+      if (typeof value !== "string") report(errors, location, "default must be a CSS color string");
+      break;
+    case "choose":
+    case "select":
+      if (Array.isArray(definition.choose) && !definition.choose.some(choice => matchesChoice(value, choice))) report(errors, location, "default is not a declared choice");
+      break;
+    case "multi":
+      if (!Array.isArray(value)) report(errors, location, "default must be an array");
+      else if (Array.isArray(definition.choose)) for (const item of value) {
+        if (!definition.choose.some(choice => matchesChoice(item, choice))) report(errors, location, `default contains undeclared choice ${JSON.stringify(item)}`);
+      }
+      break;
+    case "set":
+      if (!Array.isArray(value)) report(errors, location, "default must be an array of records");
+      else if (isObject(definition.meta)) {
+        if (definition.max != null && value.length > Number(definition.max)) report(errors, location, "default contains more items than max");
+        value.forEach((record, index) => validateRecord(record, definition.meta, `${location}[${index}]`));
+      }
+      break;
+    case "selector": {
+      const index = Number(value);
+      if (!Number.isInteger(index) || index < 1) report(errors, location, "default must be a one-based positive integer");
+      break;
+    }
+    case "action":
+      if (typeof value !== "number" || !Number.isFinite(value)) report(errors, location, "default must be a finite timestamp");
+      break;
+    case "reset":
+      break;
+  }
+}
+
+function validateRecord(record, meta, location) {
+  if (!isObject(record)) {
+    report(errors, location, "must be an object");
+    return;
+  }
+  for (const key of Object.keys(record)) {
+    if (!Object.hasOwn(meta, key)) report(errors, location, `unknown record field ${key}`);
+    else validateValue(record[key], meta[key], `${location}.${key}`);
+  }
+}
+
+function validateDefinition(key, definition, manifestFile, nested = false) {
+  const location = `${manifestFile}#meta.${key}`;
+  if (!key.split("/").every(segment => PATH_SEGMENT.test(segment))) report(errors, location, "invalid parameter path");
+  if (!isObject(definition)) {
+    report(errors, location, "definition must be an object");
+    return;
+  }
+  if (!SUPPORTED_TYPES.has(definition.type)) {
+    report(errors, location, `unsupported type ${JSON.stringify(definition.type)}`);
+    return;
+  }
+  if (definition.phase != null && !["edit", "play"].includes(definition.phase)) report(errors, location, "phase must be edit or play");
+  if (definition.when != null) {
+    if (!isObject(definition.when)) report(errors, location, "when must be an object");
+    else {
+      if (typeof definition.when.key !== "string" || !definition.when.key.split("/").every(segment => PATH_SEGMENT.test(segment))) report(errors, location, "when.key must be a valid non-empty parameter path");
+      if (!Object.hasOwn(definition.when, "is") || definition.when.is === null || !["string", "number", "boolean"].includes(typeof definition.when.is)) report(errors, location, "when.is must be a string, number, or boolean");
+    }
+  }
+  if (definition.source != null && (typeof definition.source !== "string" || !definition.source.split("/").every(segment => PATH_SEGMENT.test(segment)))) report(errors, location, "source must be a valid non-empty parameter path");
+  if (["choose", "select", "multi"].includes(definition.type) && !Array.isArray(definition.choose)) report(errors, location, `${definition.type} requires a choose array`);
+  if (definition.type === "set" && !isObject(definition.meta)) report(errors, location, "set requires a meta object");
+  if (definition.type === "set" && isObject(definition.meta)) {
+    for (const [field, nestedDefinition] of Object.entries(definition.meta)) validateDefinition(field, nestedDefinition, location, true);
+  }
+  if (definition.type === "selector") {
+    if (typeof definition.set !== "string" || !definition.set.trim()) report(errors, location, "selector requires a non-empty set path");
+    if (definition.include != null && (!Array.isArray(definition.include) || definition.include.some(item => typeof item !== "string"))) report(errors, location, "selector include must be an array of strings");
+  }
+  if (definition.type === "reset" && !isObject(definition.values)) report(errors, location, "reset requires a values object");
+  if (Object.hasOwn(definition, "default")) validateValue(definition.default, definition, `${location}.default`);
+  else if (!nested && !definition.source && !["reset", "action", "selector"].includes(definition.type)) report(warnings, location, "has no default");
+}
+
+function validateConditionalTargets(meta, manifestFile, prefix = "meta") {
+  for (const [key, definition] of Object.entries(meta)) {
+    const location = `${manifestFile}#${prefix}.${key}`;
+    if (isObject(definition?.when) && typeof definition.when.key === "string" && !Object.hasOwn(meta, definition.when.key)) {
+      report(errors, location, `when.key ${definition.when.key} is not declared in the same meta object`);
+    }
+    const controllingDefinition = isObject(definition?.when) ? meta[definition.when.key] : null;
+    if (["choose", "select"].includes(controllingDefinition?.type) && Array.isArray(controllingDefinition.choose)
+      && !controllingDefinition.choose.some(choice => matchesChoice(definition.when.is, choice))) {
+      report(errors, location, `when.is is not a declared choice of ${definition.when.key}`);
+    }
+    if (definition?.type === "set" && isObject(definition.meta)) validateConditionalTargets(definition.meta, manifestFile, `${prefix}.${key}.meta`);
+  }
+}
+
+function validateManifest(templateDirectory) {
+  const manifestFile = path.join(templateDirectory, "manifest.json");
+  if (!fs.existsSync(manifestFile)) {
+    report(errors, templateDirectory, "missing manifest.json");
+    return;
+  }
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestFile, "utf8"));
+  } catch (error) {
+    report(errors, manifestFile, `invalid JSON: ${error.message}`);
+    return;
+  }
+  if (!isObject(manifest)) report(errors, manifestFile, "manifest must be an object");
+  if (!isObject(manifest?.meta)) {
+    report(errors, manifestFile, "meta must be an object");
+    return;
+  }
+  if (manifest.instructions != null && typeof manifest.instructions !== "string") report(errors, manifestFile, "instructions must be a string");
+  for (const [key, definition] of Object.entries(manifest.meta)) validateDefinition(key, definition, manifestFile);
+  validateConditionalTargets(manifest.meta, manifestFile);
+
+  for (const [key, definition] of Object.entries(manifest.meta)) {
+    if (definition.type === "selector" && !Object.hasOwn(manifest.meta, definition.set)) report(errors, `${manifestFile}#meta.${key}`, `selector set ${definition.set} is not declared`);
+    if (definition.type === "reset" && isObject(definition.values)) for (const resetPath of Object.keys(definition.values)) {
+      const canonical = manifest.meta[resetPath]?.source || resetPath;
+      if (!Object.hasOwn(manifest.meta, canonical)) report(errors, `${manifestFile}#meta.${key}`, `reset target ${resetPath} is not declared`);
+    }
+  }
+}
+
+function validateHtml(templateDirectory) {
+  const htmlFile = path.join(templateDirectory, "index.html");
+  const html = fs.readFileSync(htmlFile, "utf8");
+  if (!/nebular-overlay:update/.test(html)) report(warnings, htmlFile, "does not listen for nebular-overlay:update");
+  if (!/background\s*:\s*transparent/i.test(html)) report(warnings, htmlFile, "transparent page background was not detected");
+  if (/(?:src|href)\s*=\s*["']https?:\/\//i.test(html)) report(errors, htmlFile, "contains an external asset URL");
+  if (/\b(fetch|XMLHttpRequest|WebSocket|EventSource|Worker|SharedWorker|AudioContext)\s*\(/.test(html)) report(errors, htmlFile, "uses a blocked runtime API");
+  if (/<(?:iframe|object|embed|video|audio|canvas)\b/i.test(html)) report(errors, htmlFile, "contains a blocked element");
+  const scripts = [...html.matchAll(/<script(?:\s[^>]*)?>([\s\S]*?)<\/script>/gi)];
+  for (const [index, match] of scripts.entries()) {
+    try {
+      new Function(match[1]);
+    } catch (error) {
+      report(errors, htmlFile, `inline script ${index + 1} has invalid syntax: ${error.message}`);
+    }
+  }
+}
+
+function validateAssets(templateDirectory) {
+  for (const file of walk(templateDirectory)) {
+    const relative = path.relative(templateDirectory, file);
+    if (["index.html", "manifest.json"].includes(relative)) continue;
+    const extension = path.extname(file).toLowerCase();
+    if (!SUPPORTED_ASSETS.has(extension)) report(errors, file, `unsupported template asset ${extension || "without extension"}`);
+    if (fs.statSync(file).size > MAX_ASSET_SIZE) report(errors, file, "asset exceeds 5 MiB");
+  }
+}
+
+const target = path.resolve(process.argv[2] || ".");
+if (!fs.existsSync(target) || !fs.statSync(target).isDirectory()) {
+  console.error(`Not a directory: ${target}`);
+  process.exit(2);
+}
+const files = walk(target);
+const templateDirectories = files.filter(file => path.basename(file) === "index.html").map(file => path.dirname(file));
+if (templateDirectories.length === 0) {
+  console.error(`No templates found beneath ${target}`);
+  process.exit(2);
+}
+
+for (const templateDirectory of templateDirectories) {
+  const relative = path.relative(target, templateDirectory);
+  if (relative && !relative.split(path.sep).every(segment => PATH_SEGMENT.test(segment))) report(errors, templateDirectory, "template path contains an invalid segment");
+  const nested = templateDirectories.find(candidate => candidate !== templateDirectory && candidate.startsWith(`${templateDirectory}${path.sep}`));
+  if (nested) report(errors, templateDirectory, `contains nested template ${path.relative(templateDirectory, nested)}`);
+  validateManifest(templateDirectory);
+  validateHtml(templateDirectory);
+  validateAssets(templateDirectory);
+}
+
+for (const warning of warnings) console.warn(`WARN  ${warning}`);
+for (const error of errors) console.error(`ERROR ${error}`);
+console.log(`Checked ${templateDirectories.length} template${templateDirectories.length === 1 ? "" : "s"}: ${errors.length} error(s), ${warnings.length} warning(s)`);
+process.exitCode = errors.length ? 1 : 0;

package/templates/all/broadcast/breaking-news/index.html

@@ -0,0 +1,100 @@
+<!doctype html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <title>Breaking News</title>
+    <style>
+        * {
+            box-sizing: border-box
+        }
+
+        html, body {
+            width: 100%;
+            height: 100%;
+            margin: 0;
+            overflow: hidden;
+            background: transparent
+        }
+
+        body {
+            color: #fff;
+            font-family: Inter, system-ui, sans-serif
+        }
+
+        .strap {
+            position: absolute;
+            left: 3%;
+            right: 3%;
+            bottom: 5%;
+            display: grid;
+            grid-template-columns:auto 1fr;
+            border-radius: .65rem;
+            overflow: hidden;
+            box-shadow: 0 1rem 3rem #0005
+        }
+
+        .label {
+            display: grid;
+            place-items: center;
+            padding: 0 1.5rem;
+            background: #e12c36;
+            font-weight: 900;
+            letter-spacing: .08em;
+            text-transform: uppercase;
+            font-size: 3rem;
+        }
+
+        .copy {
+            min-width: 0;
+            background: #0c1018f2
+        }
+
+        .headline {
+            padding: .75rem 1.25rem .3rem;
+            font-size: 3rem;
+            font-weight: 850
+        }
+
+        .ticker {
+            padding: 0 1.25rem .75rem;
+            color: #cbd2dc;
+            font-size: 3rem;
+            white-space: nowrap;
+            overflow: hidden
+        }
+
+        .ticker span {
+            display: inline-block;
+            min-width: 100%;
+            animation: crawl 60s linear infinite
+        }
+
+        @keyframes crawl {
+            from {
+                transform: translateX(100%)
+            }
+            to {
+                transform: translateX(-100%)
+            }
+        }
+    </style>
+</head>
+<body>
+<section class="strap">
+    <div class="label" id="label">Breaking</div>
+    <div class="copy">
+        <div class="headline" id="headline">Nebular launches a new generation of live graphics</div>
+        <div class="ticker"><span id="ticker">More information will follow throughout the broadcast · Stay tuned</span></div>
+    </div>
+</section>
+<script>
+	const $ = id => document.getElementById(id);
+	window.addEventListener("nebular-overlay:update", ({detail}) => {
+		if (detail.news?.label != null) $("label").textContent = detail.news.label;
+		if (detail.news?.headline != null) $("headline").textContent = detail.news.headline;
+		if (detail.news?.ticker != null) $("ticker").textContent = detail.news.ticker;
+		if (detail.style?.color != null) $("label").style.backgroundColor = detail.style.color
+	});
+</script>
+</body>
+</html>

package/templates/all/broadcast/breaking-news/manifest.json

@@ -0,0 +1,9 @@
+{
+  "instructions": "Enter the breaking-news label, headline and ticker text, choose an accent colour, then press Update. Use short headlines and concise ticker copy so both remain comfortably readable on screen.",
+  "meta": {
+  "news/label": {"type": "string", "phase": "play", "label": "Label", "hint": "Enter short label", "default": "BREAKING"},
+  "news/headline": {"type": "string", "phase": "play", "label": "Headline", "hint": "Enter headline", "default": "Nebular launches a new generation of live graphics"},
+  "news/ticker": {"type": "string", "phase": "play", "label": "Ticker", "hint": "Enter ticker text", "default": "More information will follow throughout the broadcast · Stay tuned"},
+  "style/color": {"type": "color", "phase": "edit", "label": "label", "hint": "Accent colour used by the breaking-news graphic", "default": "#e12c36"}
+  }
+}

package/templates/all/broadcast/empty/index.html

@@ -0,0 +1,46 @@
+<html>
+<head>
+    <style>
+        body {
+            font-family: sans-serif;
+            margin: 1.5rem;
+            color: white;
+        }
+
+        h1 {
+            font-weight: bold;
+        }
+
+        #logo {
+            position: absolute;
+            right: 1rem;
+            top: 1rem;
+            display: none;
+            width: 10rem;
+        }
+
+        #logo.on {
+            display: block;
+        }
+
+    </style>
+    <script>
+
+
+		window.addEventListener("nebular-overlay:update", ({detail}) => {
+
+			const
+				programElement = document.getElementById("program"),
+				logoElement = document.getElementById("logo");
+
+			if (typeof detail.program === "string") programElement.textContent = detail.program;
+			if (detail.logo) logoElement.classList.toggle("on", detail.logo === "on");
+		});
+
+    </script>
+</head>
+<body>
+<h1 id="program"></h1>
+<img id="logo" src="nebular.medallion.transparent.png">
+</body>
+</html>

package/templates/all/broadcast/empty/manifest.json

@@ -0,0 +1,7 @@
+{
+  "instructions": "Empty overlay with the program name",
+  "meta": {
+    "program": {"type": "string", "default": "", "hint": "Type the program name", "label": "Program Name"},
+    "logo": {"type": "choose", "default": "off", "hint": "Logo ON/OFF", "label": "Logo Visibility", "choose": ["on", "off"]}
+  }
+}

package/templates/all/broadcast/event-countdown/index.html

@@ -0,0 +1,160 @@
+<!doctype html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <title>Event Countdown</title>
+    <style>
+        * {
+            box-sizing: border-box
+        }
+
+        html, body {
+            width: 100%;
+            height: 100%;
+            margin: 0;
+            overflow: hidden;
+            background: transparent
+        }
+
+        body {
+            font-family: Inter, Arial, Helvetica, sans-serif;
+        }
+
+        .countdown-card {
+            --panel: #fff;
+            --ink: #090909;
+            position: absolute;
+            top: 4.5%;
+            right: 4.5%;
+            filter: drop-shadow(0 1rem 2.25rem #0007);
+            display: flex;
+            flex-direction: column;
+            align-items: center;
+        }
+
+        .clock {
+            display: flex;
+            color: var(--ink);
+            overflow: hidden;
+            font-size: 3rem;
+            font-weight: bold;
+            line-height: 3rem;
+        }
+
+        .clock span {
+            background: var(--panel);
+            margin: 0 0.1rem;
+            padding: 0 0.1rem;
+        }
+
+        .time {
+            min-width: 0;
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            white-space: nowrap
+        }
+
+        .days-label {
+            background: var(--panel);
+            font-variant: all-petite-caps;
+        }
+
+        .logo-frame {
+            width: 100%;
+            min-height: 9rem;
+            max-height: 22rem;
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            overflow: hidden;
+            background: transparent
+        }
+
+        .logo {
+            display: block;
+            width: 100%;
+            height: auto;
+            max-height: 22rem;
+            object-fit: contain;
+            object-position: center top;
+            margin-top: -2rem;
+        }
+
+        .logo-missing {
+            display: none;
+            width: 100%;
+            padding: 2.5rem 1rem;
+            color: #fff;
+            background: #111d;
+            text-align: center;
+            font-size: 2rem;
+            font-weight: 850;
+            letter-spacing: .08em;
+            text-transform: uppercase
+        }
+    </style>
+</head>
+<body>
+<main class="countdown-card" id="card">
+    <section class="clock" aria-label="Event countdown">
+        <div class="days-number" id="days">00</div>
+        <div class="days-label" id="daysLabel">D</div>
+        <div class="time" id="time">00:00:00</div>
+    </section>
+    <div class="logo-frame">
+        <img class="logo" id="logo" src="logo.png" alt="Event logo">
+        <div class="logo-missing" id="logoMissing">logo.png</div>
+    </div>
+</main>
+
+<script>
+	const card = document.getElementById("card");
+	const days = document.getElementById("days");
+	const daysLabel = document.getElementById("daysLabel");
+	const time = document.getElementById("time");
+	const logo = document.getElementById("logo");
+	const logoMissing = document.getElementById("logoMissing");
+	let startsAt = 1795046400000;
+	let timer = null;
+
+	const
+		pad = value => String(value).padStart(2, "0"),
+		spanner = (str) => "<span>" + (str.split("").join("</span><span>")) + "</span>";
+
+	function renderCountdown() {
+		const remaining = Math.max(0, startsAt - Date.now());
+		const totalSeconds = Math.floor(remaining / 1000);
+		const dayCount = Math.floor(totalSeconds / 86400);
+		const hours = Math.floor(totalSeconds % 86400 / 3600);
+		const minutes = Math.floor(totalSeconds % 3600 / 60);
+		const seconds = totalSeconds % 60;
+
+		days.innerHTML = spanner(pad(dayCount));
+		time.innerHTML = spanner(`${pad(hours)}:${pad(minutes)}:${pad(seconds)}`);
+
+		clearTimeout(timer);
+		window.invalidate?.();
+		if (remaining > 0) timer = setTimeout(renderCountdown, 1000 - Date.now() % 1000 + 15);
+	}
+
+	logo.addEventListener("error", () => {
+		logo.style.display = "none";
+		logoMissing.style.display = "block";
+	});
+
+	window.addEventListener("nebular-overlay:update", ({detail}) => {
+		if (detail.event?.startsAt != null) {
+			const nextStartsAt = Number(detail.event.startsAt);
+			if (Number.isFinite(nextStartsAt)) startsAt = nextStartsAt;
+			renderCountdown();
+		}
+		if (detail.content?.days != null) daysLabel.textContent = detail.content.days;
+		if (detail.style?.color) card.style.setProperty("--panel", detail.style.color);
+		if (detail.style?.textColor) card.style.setProperty("--ink", detail.style.textColor);
+	});
+
+	renderCountdown();
+</script>
+</body>
+</html>

package/templates/all/broadcast/event-countdown/manifest.json

@@ -0,0 +1,33 @@
+{
+  "instructions": "Choose the event date and time, then add logo.png to the template directory. The countdown is derived from that fixed moment and stops at zero when the event begins.",
+  "meta": {
+    "event/startsAt": {
+      "type": "date",
+      "phase": "edit",
+      "label": "Event date and time",
+      "hint": "Choose the event date and time",
+      "default": 1795046400000
+    },
+    "content/days": {
+      "type": "string",
+      "phase": "edit",
+      "label": "Days label",
+      "hint": "Days",
+      "default": "Days"
+    },
+    "style/color": {
+      "type": "color",
+      "phase": "edit",
+      "label": "Countdown colour",
+      "hint": "Background colour behind the countdown",
+      "default": "#ffffff"
+    },
+    "style/textColor": {
+      "type": "color",
+      "phase": "edit",
+      "label": "Text colour",
+      "hint": "Countdown numbers and label colour",
+      "default": "#090909"
+    }
+  }
+}