npm - @nebularstreams/overlay-sdk - Versions diffs - 1.0.0 - Mend

@nebularstreams/overlay-sdk 1.0.0

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 (133) hide show

package/skill/nebular-overlay/references/examples.md ADDED Viewed

@@ -0,0 +1,327 @@
+## Typical Examples
+### A Bingo
+Note how Phase is used so the operator toggles between play mode and edit mode and the auto-generated UI editor is not clogged
+- In Edit Mode it allows to configure the branding-related fields
+- In Play Mode it just displays the card to click on called numbers
+**manifest.json**
+```
+{
+  "instructions": "Select each number as it is called, then press Update. The most recently selected number is highlighted and displayed automatically. Use Reset balls to clear the selection, then press Update to publish the reset. Update the event copy before play if desired.",
+  "meta": {
+    "content/eyebrow": {
+      "type": "string",
+      "phase": "edit",
+      "label": "Current number label", "hint": "Enter short label",
+      "default": "JUST CALLED"
+    },
+    "content/title": {
+      "type": "string",
+      "phase": "edit",
+      "label": "Event title", "hint": "Enter event title",
+      "default": "Friday Night Bingo"
+    },
+    "content/subtitle": {
+      "type": "string",
+      "phase": "edit",
+      "label": "Subtitle", "hint": "Enter subtitle",
+      "default": "Eyes down — good luck!"
+    },
+    "game/called": {
+      "type": "multi",
+      "phase": "play",
+      "label": "Called numbers", "hint": "Numbers called so far; the latest selection is highlighted",
+      "container": "big",
+      "choose": [
+        1, 2, 3, 4, 5, 6, 7, 8, 9, 10,
+        11, 12, 13, 14, 15, 16, 17, 18, 19, 20,
+        21, 22, 23, 24, 25, 26, 27, 28, 29, 30,
+        31, 32, 33, 34, 35, 36, 37, 38, 39, 40,
+        41, 42, 43, 44, 45, 46, 47, 48, 49, 50,
+        51, 52, 53, 54, 55, 56, 57, 58, 59, 60,
+        61, 62, 63, 64, 65, 66, 67, 68, 69, 70,
+        71, 72, 73, 74, 75, 76, 77, 78, 79, 80,
+        81, 82, 83, 84, 85, 86, 87, 88, 89, 90
+      ],
+      "cols": 10,
+      "rows": 9,
+      "responsive": true,
+      "default": [3, 8, 17, 24, 31, 42, 56, 7]
+    },
+    "game/reset": {
+      "type": "reset",
+      "phase": "play",
+      "icon": "undo",
+      "text": "Reset balls", "hint": "Clear every called number",
+      "values": {
+        "game/called": []
+      }
+    }
+  }
+}
+```
+**index.html**
+```
+<body>
+<main class="bingo">
+    <section class="caller">
+        <div class="eyebrow" id="eyebrow">Just called</div>
+        <div class="ball" id="ball">73</div>
+        <div class="title" id="title">Friday Night Bingo</div>
+        <div class="subtitle" id="subtitle">Eyes down — good luck!</div>
+        <div class="count" id="count">8 numbers called</div>
+    </section>
+    <section class="board">
+        <div class="board-header">
+            <strong>CALLED NUMBERS</strong>
+            <span class="legend">WHITE · CALLED&nbsp;&nbsp;&nbsp; ORANGE · CURRENT</span>
+        </div>
+        <div class="numbers" id="numbers"></div>
+    </section>
+</main>
+<script>
+	const
+		MAX_NUMBER = 90,
+		$ = (id) => document.getElementById(id),
+		cells = new Map();
+	let called = [];
+	for (let number = 1; number <= MAX_NUMBER; number++) {
+		const cell = document.createElement("div");
+		cell.className = "number";
+		cell.textContent = number;
+		$("numbers").append(cell);
+		cells.set(number, cell);
+	}
+	function updateBoard() {
+		const
+			values = (Array.isArray(called) ? called : []).map(Number).filter(number => number >= 1 && number <= MAX_NUMBER),
+			currentNumber = values.at(-1),
+			calledNumbers = new Set(values);
+		cells.forEach((cell, number) => {
+			cell.classList.toggle("called", calledNumbers.has(number));
+			cell.classList.toggle("current", number === currentNumber);
+		});
+		const ballValue = currentNumber ?? "—";
+		if ($("ball").textContent !== String(ballValue)) {
+			const replacement = $("ball").cloneNode(false);
+			replacement.textContent = ballValue;
+			$("ball").replaceWith(replacement);
+		}
+		$("count").textContent = `${calledNumbers.size} ${calledNumbers.size === 1 ? "number" : "numbers"} called`;
+	}
+	window.addEventListener("nebular-overlay:update", ({detail}) => {
+		if (detail.content?.eyebrow != null) $("eyebrow").textContent = detail.content.eyebrow;
+		if (detail.content?.title != null) $("title").textContent = detail.content.title;
+		if (detail.content?.subtitle != null) $("subtitle").textContent = detail.content.subtitle;
+		if (detail.game?.called != null) called = detail.game.called;
+		if (detail.game?.called != null) updateBoard();
+	})
+</script>
+```
+### An automatic news ticker
+**manifest.json**
+```
+{
+  "instructions": "Build the running news list in playback order. Each item remains on screen for the selected interval; its headline slides upward to the next item, while the topic changes only when the next item belongs to a different topic.",
+  "meta": {
+    "content/brand": {"type": "string", "phase": "edit", "label": "Brand text", "hint": "US OPEN", "default": "US OPEN"},
+    "news": {
+      "type": "set", "phase": "edit", "label": "News items", "hint": "Headlines shown in their playback order", "container": "big", "max": 30,
+      "default": [
+        {"topic": "MEN'S DOUBLES", "tagline": "Carlos Alcaraz defeats Tommy Paul in memorable performance, 6-4 6–4 6–2"},
+        {"topic": "MEN'S DOUBLES", "tagline": "The quarter-final line-up is now complete in New York"},
+        {"topic": "WOMEN'S SINGLES", "tagline": "A dramatic final set sends the defending champion through"},
+        {"topic": "AROUND THE GROUNDS", "tagline": "Evening play begins under the lights at Arthur Ashe Stadium"}
+      ],
+      "meta": {
+        "topic": {"type": "string", "phase": "edit", "label": "News topic", "hint": "MEN'S DOUBLES"},
+        "tagline": {"type": "string", "phase": "edit", "label": "News tagline", "hint": "Enter headline"}
+      }
+    },
+    "timing/interval": {"type": "number", "phase": "edit", "label": "News interval", "hint": "Seconds between headlines", "default": 5, "min": 2, "max": 30},
+    "style/background": {"type": "color", "phase": "edit", "label": "Background", "hint": "Background colour used by the ticker", "default": "#0759a6"}
+  }
+}
+```
+**index.html**
+(excluding styles, etc)
+```
+<body>
+<main class="ticker" id="ticker">
+    <section class="zone topic"><div class="viewport" id="topicSlot">
+        <div class="line">MEN'S DOUBLES</div><div class="line waiting"></div>
+    </div></section>
+    <section class="zone headline"><div class="viewport" id="headlineSlot">
+        <div class="line">Carlos Alcaraz defeats Tommy Paul, 7–6 7–6 6–4</div><div class="line waiting"></div>
+    </div></section>
+    <section class="zone brand"><div class="viewport"><div class="line" id="brand">US OPEN</div></div></section>
+</main>
+<script>
+    const defaults = [
+        {topic: "MEN'S DOUBLES", tagline: "Carlos Alcaraz defeats Tommy Paul in memorable performance, 6–4 6–4 6–2"},
+        {topic: "MEN'S DOUBLES", tagline: "The quarter-final line-up is now complete in New York"},
+        {topic: "WOMEN'S SINGLES", tagline: "A dramatic final set sends the defending champion through"},
+        {topic: "AROUND THE GROUNDS", tagline: "Evening play begins under the lights at Arthur Ashe Stadium"}
+    ];
+    const TRANSITION_MS = 580;
+    const ticker = document.getElementById("ticker");
+    const brand = document.getElementById("brand");
+    function makeSlot(id) {
+        const lines = document.getElementById(id).querySelectorAll(".line");
+        return {current: lines[0], next: lines[1], timer: null};
+    }
+    const topicSlot = makeSlot("topicSlot");
+    const headlineSlot = makeSlot("headlineSlot");
+    let items = defaults;
+    let currentIndex = 0;
+    let intervalSeconds = 5;
+    let cycleTimer = null;
+    function cleanItems(value) {
+        if (!Array.isArray(value)) return [];
+        return value.map(item => ({
+            topic: String(item?.topic ?? "").trim(),
+            tagline: String(item?.tagline ?? "").trim()
+        })).filter(item => item.topic || item.tagline);
+    }
+    function setSlot(slot, text) {
+        clearTimeout(slot.timer);
+        slot.current.textContent = text;
+        slot.current.className = "line";
+        slot.next.textContent = "";
+        slot.next.className = "line waiting";
+    }
+    function animateSlot(slot, text) {
+        clearTimeout(slot.timer);
+        slot.next.textContent = text;
+        slot.next.className = "line waiting";
+        void slot.next.offsetHeight;
+        slot.current.className = "line leaving";
+        slot.next.className = "line";
+        slot.timer = setTimeout(() => {
+            const previous = slot.current;
+            slot.current = slot.next;
+            slot.next = previous;
+            slot.next.textContent = "";
+            slot.next.className = "line waiting";
+        }, TRANSITION_MS);
+    }
+    function showCurrent() {
+        const item = items[currentIndex];
+        ticker.classList.toggle("empty", !item);
+        if (!item) return;
+        setSlot(topicSlot, item.topic);
+        setSlot(headlineSlot, item.tagline);
+    }
+    function scheduleCycle() {
+        clearTimeout(cycleTimer);
+        if (items.length > 1) cycleTimer = setTimeout(nextItem, intervalSeconds * 1000);
+    }
+    function nextItem() {
+        if (items.length < 2) return;
+        const previous = items[currentIndex];
+        currentIndex = (currentIndex + 1) % items.length;
+        const next = items[currentIndex];
+        animateSlot(headlineSlot, next.tagline);
+        if (next.topic !== previous.topic) animateSlot(topicSlot, next.topic);
+        scheduleCycle();
+    }
+    function replaceItems(value) {
+        items = cleanItems(value);
+        currentIndex = 0;
+        showCurrent();
+        scheduleCycle();
+    }
+    window.addEventListener("nebular-overlay:update", ({detail}) => {
+        if (detail.content?.brand != null) brand.textContent = detail.content.brand;
+        if (detail.style?.background) ticker.style.setProperty("--background", detail.style.background);
+        if (detail.timing?.interval != null) {
+            const interval = Number(detail.timing.interval);
+            if (Number.isFinite(interval)) intervalSeconds = Math.min(30, Math.max(2, interval));
+            scheduleCycle();
+        }
+        if (detail.news != null) replaceItems(detail.news);
+    });
+    showCurrent();
+    scheduleCycle();
+</script>
+</body>
+```
+### A simple call-to-action
+**manifest.json**
+```
+{
+  "instructions": "Configure the campaign message and call to action, then set the current and target values to update the progress indicator. Press Update whenever the campaign copy or progress changes.",
+  "meta": {
+    "content/eyebrow": {"type": "string", "phase": "edit", "label": "Eyebrow", "hint": "Enter short label", "default": "VIEWER GOAL"},
+    "content/title": {"type": "string", "phase": "edit", "label": "Title", "hint": "Enter title", "default": "Help us reach 10,000 followers"},
+    "content/subtitle": {"type": "string", "phase": "edit", "label": "Description", "hint": "Enter description", "default": "Follow the channel and join the Nebular community."},
+    "content/action": {"type": "string", "phase": "edit", "label": "Action", "hint": "e.g. FOLLOW NOW", "default": "FOLLOW NOW"},
+    "goal/playTarget": {"type": "number", "phase": "play", "label": "Target", "hint": "Goal currently used by the live progress display", "source": "goal/target", "readonly": true},
+    "goal/current": {"type": "number", "phase": "play", "label": "Current", "hint": "Enter current value", "min": 0, "default": 7240},
+    "goal/target": {"type": "number", "phase": "edit", "label": "Target", "hint": "Enter target", "min": 1, "default": 10000}
+  }
+}
+```
+**index.html**
+```
+<body>
+<section class="card">
+    <div class="eyebrow" id="eyebrow">Viewer goal</div>
+    <div class="title" id="title">Help us reach 10,000 followers</div>
+    <div class="subtitle" id="subtitle">Follow the channel and join the Nebular community.</div>
+    <div class="progress"><span id="progress"></span></div>
+    <div class="footer"><span id="action">FOLLOW NOW</span><span class="count" id="count">7,240 / 10,000</span></div>
+</section>
+<script>
+	const $ = id => document.getElementById(id);
+	const progressState = {current: 7240, target: 10000};
+	function renderProgress() {
+		const current = Math.max(0, Number(progressState.current) || 0),
+			target = Math.max(1, Number(progressState.target) || 1);
+		$("progress").style.width = `${Math.min(100, current / target * 100)}%`;
+		$("count").textContent = `${current.toLocaleString()} / ${target.toLocaleString()}`
+	}
+	window.addEventListener("nebular-overlay:update", ({detail}) => {
+		if (detail.content?.eyebrow != null) $("eyebrow").textContent = detail.content.eyebrow;
+		if (detail.content?.title != null) $("title").textContent = detail.content.title;
+		if (detail.content?.subtitle != null) $("subtitle").textContent = detail.content.subtitle;
+		if (detail.content?.action != null) $("action").textContent = detail.content.action;
+		if (detail.goal?.current != null) progressState.current = detail.goal.current;
+		if (detail.goal?.target != null) progressState.target = detail.goal.target;
+		if (detail.goal?.current != null || detail.goal?.target != null) renderProgress();
+	});
+</script>
+</body>
+```

package/skill/nebular-overlay/references/manifest.md ADDED Viewed

@@ -0,0 +1,153 @@
+# Manifest contract
+Each template has a `manifest.json` object with an optional concise `instructions` string and a required `meta` object.
+```json
+{
+  "instructions": "Configure the title before going live. Update the score during play.",
+  "meta": {
+    "content/title": {"type": "string", "phase": "edit", "label": "Title", "hint": "Enter title", "default": "Championship Final"},
+    "game/score": {"type": "number", "phase": "play", "label": "Score", "min": 0, "default": 0}
+  }
+}
+```
+Slash-separated keys become nested update values: `content/title` arrives as `detail.content.title`. Path segments should contain only letters, numbers, hyphens, and underscores.
+## Shared fields
+- `type`: required control type.
+- `label`: short operator-facing caption. Buttons may use `text` instead.
+- `default`: initial Studio value. It must agree with the initial HTML presentation.
+- `phase`: optional `edit` or `play`. Omit only when a field genuinely belongs in both modes.
+- `when`: optional conditional visibility rule in the form `{"key": "path", "is": value}`. The control is shown only while the current value at `key` strictly equals `is`.
+- `hint`: short placeholder for `string` and `date`; descriptive hover help for other controls.
+- `readonly`: displays the value without allowing edits.
+- `source`: makes this control a UI alias for another canonical value path. The alias path is not persisted.
+- `size`: optional editor column width; `break` starts a new editor row.
+- `container`: `"big"` or `"small"` editor-space preference.
+- `class`: optional Studio presentation class; use only when an established repository convention requires it.
+## Conditional controls
+Every control type supports `when`. Use it to keep a crowded Edit or Play panel focused when one value selects among several screens or operating states:
+```json
+{
+  "screen": {
+    "type": "choose",
+    "phase": "play",
+    "label": "Screen",
+    "default": "scores",
+    "choose": [
+      {"value": "scores", "caption": "Hi-Scores"},
+      {"value": "playing", "caption": "Now Playing"},
+      {"value": "idle", "caption": "Game Idle"}
+    ]
+  },
+  "current/name": {
+    "type": "string",
+    "phase": "play",
+    "label": "Current player",
+    "default": "VEX",
+    "when": {"key": "screen", "is": "playing"}
+  },
+  "idle/headline": {
+    "type": "string",
+    "phase": "play",
+    "label": "Announcement",
+    "default": "ROOK ENTERS THE ARENA",
+    "when": {"key": "screen", "is": "idle"}
+  }
+}
+```
+- `key` is a slash-separated value path and must identify another canonical control in the same `meta` object.
+- `is` is compared with strict equality, so its JSON type must match the controlling value. For example, `1` and `"1"` are different.
+- `phase` and `when` are cumulative: a control is visible only when both filters pass.
+- Conditional visibility affects only the generated editor. A hidden value remains initialized, persisted, and available to the template; hiding it never clears or resets it.
+- Prefer one clear controlling field such as `screen` over chains of interdependent conditions. `when` supports one equality test, not compound expressions.
+- In a nested `set` record, `key` refers to a sibling field in that record's nested `meta`.
+## Types
+### `string`
+A text input. `default` is a string. Supports `maxLength` and `pattern`. Keep `hint` short because it appears inside the empty input.
+### `number` and `range`
+Numeric controls supporting `min`, `max`, and (for `range`) `step`. Studio may emit numeric input values as strings, so page logic should convert with `Number(...)` when arithmetic matters.
+### `date`
+A local date-time picker whose persisted value is a finite Unix epoch in milliseconds. Use a numeric default such as `1795046400000`. The page can compare it directly with `Date.now()`.
+### `color`
+A color picker. The default is a CSS color string. Optional fields include `noalpha`, `remove`, and `caption`. If `remove` is enabled, the update may contain `null`.
+### `choose` and `select`
+Single-choice controls with a `choose` array and scalar default. `choose` renders buttons; `select` renders a dropdown. Entries may be primitives or captioned objects:
+```json
+{"value": "car", "caption": "Car"}
+```
+Keep the default's type consistent with the choice values.
+### `multi`
+A multiple-choice grid. `choose` is an array and `default` is an array. Useful options are `cols`, `rows`, `responsive`, `minCellWidth`, and `container`.
+### `set`
+An editable array of records. Define record fields in nested `meta`, give `default` an array of matching objects, and usually set a practical `max`.
+```json
+"news": {
+"type": "set", "phase": "edit", "label": "News items", "container": "big", "max": 20,
+"default": [{"topic": "SPORT", "headline": "Final begins tonight"}],
+"meta": {
+"topic": {
+"type": "string", "label": "Topic", "hint": "SPORT"},
+"headline": {"type": "string", "label": "Headline", "hint": "Enter headline"
+}
+}
+}
+```
+Nested sets are supported, but prefer a flat record when it expresses the workflow; deep editors are cumbersome for operators.
+### `selector`
+A one-based index selector for a set, normally used in `play` mode. `set` is required and identifies the target value path. `include` optionally lists record fields to display beneath the selector.
+```json
+"control/current": {"type": "selector", "phase": "play", "label": "Current question", "set": "questions", "include": ["question"]}
+```
+### `action`
+A button that emits `Date.now()` at its value path. Use `text`, `icon`, and `hint`. Treat each new timestamp as a trigger; do not depend on a particular timestamp value.
+### `reset`
+A button that assigns several declared paths at once. Its `values` object maps canonical manifest paths to reset values.
+```json
+"game/reset": {
+"type": "reset", "phase": "play", "text": "Reset game", "icon": "undo",
+"hint": "Return the game to its initial state", "values": {"game/score": 0, "game/history": []
+}
+}
+```
+## Defaults and aliases
+- Do not use truthiness to read defaults or updates: `0`, `false`, `""`, and `[]` are meaningful.
+- A `source` control reads and writes the canonical source path. Do not also persist the alias key.
+- A hidden `when` control retains its value; do not rely on visibility to clear state.
+- Set and multi updates replace that entire parameter value; fields absent from an event remain unchanged.
+- Keep reset targets and selector set paths aligned with declared canonical paths.

package/skill/nebular-overlay/references/runtime-and-design.md ADDED Viewed

@@ -0,0 +1,88 @@
+# Runtime and design guidance
+## Page baseline
+Use a transparent, fixed render surface:
+```css
+* { box-sizing: border-box }
+html, body { width: 100%; height: 100%; margin: 0; overflow: hidden; background: transparent; }
+```
+Design primarily for 1920×1080. Use percentages, viewport units, grids, flex layout, and `clamp()` where they improve scaling. Keep essential graphics inside sensible title-safe margins unless the design intentionally touches an edge.
+Broadcast copy must survive motion and detailed video beneath it. Prefer:
+- large type for the primary value (roughly 40–70 px at 1080p, often larger for scores or countdowns);
+- high contrast, restrained shadows, translucent panels, or local backplates;
+- short line lengths and deliberate truncation/wrapping behavior;
+- clear hierarchy rather than many equally prominent elements;
+- tabular numerals for clocks and scores (`font-variant-numeric: tabular-nums`).
+## Incremental updates
+Every event is a patch, not a complete state replacement:
+```js
+window.addEventListener("nebular-overlay:update", ({detail = {}}) => {
+  if (detail.content?.title != null) title.textContent = detail.content.title;
+  if (detail.style?.accent != null) root.style.setProperty("--accent", detail.style.accent);
+  if (Array.isArray(detail.items)) { state.items = detail.items; renderItems(); }
+});
+```
+Use `!= null`, explicit property checks, or type checks. Do not write `if (detail.game?.score)` when zero is valid. Do not reset unrelated fields on every event.
+Treat update data as untrusted. Use `textContent`, DOM properties, and validated style values; avoid `innerHTML`. The page should already display useful sample content before the first event, and manifest defaults should match it.
+## State and animations
+Keep state local and small. Update existing nodes instead of rebuilding the whole page. For transitions, prefer opacity and transforms; avoid expensive layout animation, filters over large areas, and perpetual high-frequency work.
+Cancel or replace outstanding timers when relevant values change. Handle rapid consecutive updates without leaving duplicated nodes or stale classes.
+Clocks and countdowns must derive their display from an absolute epoch:
+```js
+function renderClock() {
+  const remaining = Math.max(0, state.startsAt - Date.now());
+  // derive days/hours/minutes/seconds from remaining
+}
+```
+Do not decrement a stored number once per second: redraws, throttling, dropped frames, and page suspension cause drift. A timestamp also keeps independent renderers synchronized closely enough for display.
+Call `window.invalidate?.()` only if a small static DOM change is not captured automatically; normal updates should not need it.
+## Assets and isolation
+Allowed local asset formats are CSS (`.css`), images (`.jpg`, `.jpeg`, `.png`, `.webp`), and fonts (`.otf`, `.ttf`, `.woff`, `.woff2`). Each served file is limited to 5 MiB. Reference assets with relative URLs. Keep JavaScript inline in `index.html`; local JavaScript files are not served.
+Do not use external URLs or attempt network access. The production renderer blocks external scripts, styles, fonts, images, `fetch`, XHR, WebSocket, EventSource, audio/video resources, frames, embedded objects, forms, workers, popups, storage, WebGL, canvas rendering, WASM, WebAudio, and device APIs.
+Avoid large DOMs, large assets, tight loops, aggressive timers, and expensive effects. Templates are reviewed for render cost even when their APIs are technically permitted.
+## Useful implementation patterns
+- Put editable colors into CSS custom properties and update the property.
+- Use `object-fit: contain` for optional organization-supplied logos.
+- Give missing assets a restrained fallback rather than breaking the composition.
+- For a `selector`, clamp the one-based value to the current set length before indexing.
+- When a set becomes empty, render a deliberate empty state or hide the graphic.
+- For repeated ticker items, maintain the current index and restart scheduling only when the list or timing changes.
+- If a topic repeats across consecutive ticker items, animate only the changing headline.
+## Local test events
+Exercise both full and partial patches from the browser console:
+```js
+window.dispatchEvent(new CustomEvent("nebular-overlay:update", {
+  detail: {content: {title: "Local preview"}, style: {accent: "#ff9818"}}
+}));
+window.dispatchEvent(new CustomEvent("nebular-overlay:update", {
+  detail: {content: {title: "Only the title changes"}}
+}));
+```
+Verify that the second event does not reset the accent or any internal play state.